aiquila-mcp 0.3.28 → 0.3.30

package/dist/auth/provider.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 import { createHash, timingSafeEqual } from 'node:crypto';
 import { SignJWT, jwtVerify } from 'jose';
-import { InvalidGrantError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { InvalidGrantError, InvalidTokenError, } from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import { ClientsStore, CodeStore, RefreshStore } from './store.js';
 import { logger } from '../logger.js';
 // --- JWT helpers (HMAC-SHA256 via jose) ---
@@ -196,7 +196,10 @@ export class NextcloudOAuthProvider {
         const claims = await verifyJwt(token, this.getSecret(), issuer ? { issuer, audience: new URL('/mcp', issuer).toString() } : undefined);
         if (!claims) {
             logger.warn('[auth] Access token verification failed: invalid or expired token');
-            throw new Error('Invalid or expired access token');
+            // InvalidTokenError (not a bare Error) so the SDK answers 401 with a
+            // WWW-Authenticate challenge. A bare Error becomes a 500, and clients
+            // treat that as a server fault rather than a cue to re-authenticate.
+            throw new InvalidTokenError('Invalid or expired access token');
         }
         return {
             token,

package/dist/server.js

@@ -25,7 +25,9 @@ export async function createServer() {
         for (const tool of toolSet) {
             const name = tool.name;
             server.registerTool(name, {
+                title: tool.title,
                 description: tool.description,
+                annotations: tool.annotations,
                 inputSchema: tool.inputSchema,
             }, async (...args) => {
                 const start = Date.now();

package/dist/tool-registry.js

@@ -156,7 +156,10 @@ async function detectEnabledApps() {
         return apps;
     }
     catch (err) {
-        logger.warn({ err: err instanceof Error ? err.message : String(err) }, '[startup] Could not detect enabled apps — registering all tools');
+        logger.warn({ err: err instanceof Error ? err.message : String(err) }, '[startup] Could not detect enabled apps — registering ALL tools as a fallback. ' +
+            '/ocs/v2.php/cloud/apps requires admin credentials; a non-admin NEXTCLOUD_USER always ' +
+            'lands here. Set MCP_TOOLS to an explicit category/tool whitelist, or use an admin app ' +
+            'password, to register only the tools you need.');
         return null;
     }
 }
@@ -186,6 +189,15 @@ function filterByEnabledApps(enabledApps) {
 }
 // Cached result — cleared only on process restart
 let cachedToolSets = null;
+/**
+ * Tool count above which we warn. Not a protocol limit — no MCP client documents one —
+ * but very large tool lists are worth flagging, and reaching this number usually means
+ * app-detection fell back to registering everything.
+ */
+export const HIGH_TOOL_COUNT = 100;
+function countTools(toolSets) {
+    return toolSets.reduce((sum, ts) => sum + ts.length, 0);
+}
 /**
  * Returns filtered tool arrays based on MCP_TOOLS env var or auto-detection.
  * Result is cached after first call.
@@ -194,16 +206,21 @@ export async function getFilteredToolSets() {
     if (cachedToolSets)
         return cachedToolSets;
     const mcpToolsFilter = parseMcpTools();
+    let source;
     if (mcpToolsFilter) {
         cachedToolSets = filterByExplicitList(mcpToolsFilter);
-        const toolCount = cachedToolSets.reduce((sum, ts) => sum + ts.length, 0);
-        logger.info({ tools: toolCount, source: 'MCP_TOOLS' }, '[startup] Tool filtering applied');
+        source = 'MCP_TOOLS';
     }
     else {
         const enabledApps = await detectEnabledApps();
         cachedToolSets = filterByEnabledApps(enabledApps);
-        const toolCount = cachedToolSets.reduce((sum, ts) => sum + ts.length, 0);
-        logger.info({ tools: toolCount, source: enabledApps ? 'app-detection' : 'all (fallback)' }, '[startup] Tool filtering applied');
+        source = enabledApps ? 'app-detection' : 'all (fallback)';
+    }
+    const toolCount = countTools(cachedToolSets);
+    logger.info({ tools: toolCount, source }, '[startup] Tool filtering applied');
+    if (toolCount > HIGH_TOOL_COUNT) {
+        logger.warn({ tools: toolCount, threshold: HIGH_TOOL_COUNT, source }, `[startup] Registering ${toolCount} tools. Set MCP_TOOLS to a category/tool whitelist to ` +
+            'narrow this down — some clients degrade on very large tool lists.');
     }
     return cachedToolSets;
 }

package/dist/tools/apps/absence.js

@@ -11,6 +11,13 @@ import { getNextcloudConfig } from '../types.js';
 // ---------------------------------------------------------------------------
 export const getOutOfOfficeTool = {
     name: 'get_out_of_office',
+    title: 'Get Out-of-Office Status',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: "Get a user's current out-of-office / absence status (NC 28+)",
     inputSchema: z.object({
         userId: z
@@ -49,6 +56,13 @@ export const getOutOfOfficeTool = {
 // ---------------------------------------------------------------------------
 export const setOutOfOfficeTool = {
     name: 'set_out_of_office',
+    title: 'Set Out-of-Office Status',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Set an out-of-office / absence period with status message (NC 28+)',
     inputSchema: z.object({
         firstDay: z.string().describe('First day of absence (YYYY-MM-DD)'),
@@ -107,6 +121,13 @@ export const setOutOfOfficeTool = {
 // ---------------------------------------------------------------------------
 export const clearOutOfOfficeTool = {
     name: 'clear_out_of_office',
+    title: 'Clear Out-of-Office Status',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: "Clear a user's out-of-office / absence status (NC 28+)",
     inputSchema: z.object({
         userId: z

package/dist/tools/apps/activity.js

@@ -15,6 +15,13 @@ function formatActivities(activities) {
 // ---------------------------------------------------------------------------
 export const listActivityTool = {
     name: 'list_activity',
+    title: 'List Activity',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'List recent entries from the Nextcloud activity feed (file changes, shares, ' +
         'comments, calendar/contact edits, etc.) for the current user.',
     inputSchema: z.object({
@@ -77,6 +84,13 @@ export const listActivityTool = {
 // ---------------------------------------------------------------------------
 export const getObjectActivityTool = {
     name: 'get_object_activity',
+    title: 'Get Object Activity',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'List the activity history for a single object, e.g. one file. Use object_type ' +
         "'files' with a file ID to see what happened to that file.",
     inputSchema: z.object({

package/dist/tools/apps/aiquila.js

@@ -21,6 +21,13 @@ async function runOCC(command, args = []) {
  */
 export const showConfigTool = {
     name: 'aiquila_show_config',
+    title: 'Show AIquila Configuration',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Show current AIquila configuration',
     inputSchema: z.object({}),
     handler: async () => {
@@ -52,6 +59,13 @@ export const showConfigTool = {
  */
 export const configureTool = {
     name: 'aiquila_configure',
+    title: 'Configure AIquila',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Configure AIquila settings (API key, model, tokens, timeout)',
     inputSchema: z.object({
         apiKey: z.string().optional().describe('Anthropic API key'),
@@ -104,6 +118,13 @@ export const configureTool = {
  */
 export const testTool = {
     name: 'aiquila_test',
+    title: 'Test AIquila Claude Integration',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
     description: 'Test AIquila Claude API integration with a simple prompt',
     inputSchema: z.object({
         prompt: z.string().default('Hello, Claude!').describe('Test prompt to send to Claude API'),

package/dist/tools/apps/announcements.js

@@ -21,6 +21,13 @@ function formatAnnouncements(items) {
 // ---------------------------------------------------------------------------
 export const listAnnouncementsTool = {
     name: 'list_announcements',
+    title: 'List Announcements',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'List announcements from the Nextcloud Announcement Center (org-wide notices such as ' +
         'maintenance windows, events, or news). Returns newest first.',
     inputSchema: z.object({
@@ -70,6 +77,13 @@ export const listAnnouncementsTool = {
 // ---------------------------------------------------------------------------
 export const createAnnouncementTool = {
     name: 'create_announcement',
+    title: 'Create Announcement',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
     description: 'Create a new announcement in the Announcement Center. This is visible to all or ' +
         'selected groups and can trigger notifications/emails — use deliberately. Requires the ' +
         'configured Nextcloud user to be an admin.',
@@ -142,6 +156,13 @@ export const createAnnouncementTool = {
 // ---------------------------------------------------------------------------
 export const deleteAnnouncementTool = {
     name: 'delete_announcement',
+    title: 'Delete Announcement',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Delete an announcement by its ID. Requires the configured Nextcloud user to be an admin.',
     inputSchema: z.object({
         id: z.number().describe('The announcement ID to delete'),

package/dist/tools/apps/assistant.js

@@ -14,6 +14,13 @@ const STATUS_LABELS = {
 // ---------------------------------------------------------------------------
 export const listTextTasksTool = {
     name: 'list_text_tasks',
+    title: 'List Text Tasks',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: "List AI task types available in Nextcloud's TaskProcessing framework (summarize, headline, image-to-text, text-to-image, …). Shows which task types have at least one provider configured.",
     inputSchema: z.object({}),
     handler: async () => {
@@ -54,6 +61,13 @@ export const listTextTasksTool = {
 // ---------------------------------------------------------------------------
 export const processTextTool = {
     name: 'process_text',
+    title: 'Process Text with AI',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
     description: "Submit a text-processing task to Nextcloud's AI framework and return the task ID. Use get_task_result to poll until it completes. Common task types: 'core:text2text' (free prompt), 'core:summarize' (summary), 'core:headline' (headline), 'core:extract_topics' (topics).",
     inputSchema: z.object({
         taskType: z
@@ -107,6 +121,13 @@ export const processTextTool = {
 // ---------------------------------------------------------------------------
 export const getTaskResultTool = {
     name: 'get_task_result',
+    title: 'Get AI Task Result',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Get the status and result of a Nextcloud AI task previously created by process_text or generate_image. Status: 1=scheduled, 2=running, 3=successful, 4=failed.',
     inputSchema: z.object({
         taskId: z.number().describe('The task ID returned by process_text or generate_image'),
@@ -168,6 +189,13 @@ export const getTaskResultTool = {
 // ---------------------------------------------------------------------------
 export const generateImageTool = {
     name: 'generate_image',
+    title: 'Generate Image',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
     description: "Generate an image from a text prompt using Nextcloud's text-to-image AI provider (e.g. Stable Diffusion via LocalAI). Returns the task ID; use get_task_result to check completion.",
     inputSchema: z.object({
         prompt: z.string().describe('Text description of the image to generate'),

package/dist/tools/apps/bookmarks.js

@@ -48,6 +48,13 @@ function formatFolderTree(folder, indent = 0) {
 // ── Bookmark Tools ──────────────────────────────────────────────────────────
 export const listBookmarksTool = {
     name: 'list_bookmarks',
+    title: 'List Bookmarks',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'List bookmarks from Nextcloud Bookmarks app. Supports search, tag filtering, folder filtering, sorting, and pagination.',
     inputSchema: z.object({
         search: z
@@ -122,6 +129,13 @@ export const listBookmarksTool = {
 };
 export const getBookmarkTool = {
     name: 'get_bookmark',
+    title: 'Get Bookmark',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Get full details of a single bookmark by its ID.',
     inputSchema: z.object({
         id: z.number().describe('The bookmark ID'),
@@ -153,6 +167,13 @@ export const getBookmarkTool = {
 };
 export const createBookmarkTool = {
     name: 'create_bookmark',
+    title: 'Create Bookmark',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
     description: 'Create a new bookmark in Nextcloud Bookmarks. URL is required; title, description, tags, and folders are optional.',
     inputSchema: z.object({
         url: z.string().describe('The URL to bookmark'),
@@ -200,6 +221,13 @@ export const createBookmarkTool = {
 };
 export const updateBookmarkTool = {
     name: 'update_bookmark',
+    title: 'Update Bookmark',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Update an existing bookmark. Only provided fields are changed.',
     inputSchema: z.object({
         id: z.number().describe('The bookmark ID to update'),
@@ -250,6 +278,13 @@ export const updateBookmarkTool = {
 };
 export const deleteBookmarkTool = {
     name: 'delete_bookmark',
+    title: 'Delete Bookmark',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Delete a bookmark by its ID. This action is irreversible.',
     inputSchema: z.object({
         id: z.number().describe('The bookmark ID to delete'),
@@ -282,6 +317,13 @@ export const deleteBookmarkTool = {
 // ── Folder Tools ────────────────────────────────────────────────────────────
 export const listBookmarkFoldersTool = {
     name: 'list_bookmark_folders',
+    title: 'List Bookmark Folders',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'List the bookmark folder hierarchy. Returns a tree structure of all folders.',
     inputSchema: z.object({
         root: z
@@ -328,6 +370,13 @@ export const listBookmarkFoldersTool = {
 };
 export const getBookmarkFolderContentsTool = {
     name: 'get_bookmark_folder_contents',
+    title: 'Get Bookmark Folder Contents',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Get the contents of a bookmark folder (bookmarks and subfolders).',
     inputSchema: z.object({
         id: z.number().describe('The folder ID (-1 for root)'),
@@ -382,6 +431,13 @@ export const getBookmarkFolderContentsTool = {
 };
 export const createBookmarkFolderTool = {
     name: 'create_bookmark_folder',
+    title: 'Create Bookmark Folder',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
     description: 'Create a new bookmark folder.',
     inputSchema: z.object({
         title: z.string().describe('Folder name'),
@@ -420,6 +476,13 @@ export const createBookmarkFolderTool = {
 };
 export const updateBookmarkFolderTool = {
     name: 'update_bookmark_folder',
+    title: 'Update Bookmark Folder',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Update a bookmark folder (rename or move to a different parent).',
     inputSchema: z.object({
         id: z.number().describe('The folder ID to update'),
@@ -458,6 +521,13 @@ export const updateBookmarkFolderTool = {
 };
 export const deleteBookmarkFolderTool = {
     name: 'delete_bookmark_folder',
+    title: 'Delete Bookmark Folder',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Delete a bookmark folder and all its contents. This action is irreversible.',
     inputSchema: z.object({
         id: z.number().describe('The folder ID to delete'),
@@ -490,6 +560,13 @@ export const deleteBookmarkFolderTool = {
 // ── Tag Tools ───────────────────────────────────────────────────────────────
 export const listBookmarkTagsTool = {
     name: 'list_bookmark_tags',
+    title: 'List Bookmark Tags',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'List all tags used across bookmarks.',
     inputSchema: z.object({}),
     handler: async () => {
@@ -528,6 +605,13 @@ export const listBookmarkTagsTool = {
 };
 export const renameBookmarkTagTool = {
     name: 'rename_bookmark_tag',
+    title: 'Rename Bookmark Tag',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Rename a bookmark tag. All bookmarks with the old tag will be updated.',
     inputSchema: z.object({
         old_name: z.string().describe('Current tag name'),
@@ -563,6 +647,13 @@ export const renameBookmarkTagTool = {
 };
 export const deleteBookmarkTagTool = {
     name: 'delete_bookmark_tag',
+    title: 'Delete Bookmark Tag',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Delete a bookmark tag. The tag will be removed from all bookmarks.',
     inputSchema: z.object({
         name: z.string().describe('Tag name to delete'),

package/dist/tools/apps/calendar.js

@@ -628,6 +628,13 @@ async function resolveEventByUid(calendarName, uid) {
  */
 export const listCalendarsTool = {
     name: 'list_calendars',
+    title: 'List Calendars',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'List all calendars available to the current user, including their supported component types (events, tasks, journals) and metadata.',
     inputSchema: z.object({}),
     handler: async () => {
@@ -691,6 +698,13 @@ export const listCalendarsTool = {
  */
 export const listEventsTool = {
     name: 'list_events',
+    title: 'List Calendar Events',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'List events from a Nextcloud calendar within an optional time range. Returns event details including time, location, attendees, recurrence, and UIDs.',
     inputSchema: z.object({
         calendarName: z
@@ -805,6 +819,13 @@ export const listEventsTool = {
  */
 export const getEventTool = {
     name: 'get_event',
+    title: 'Get Calendar Event',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Get detailed information about a single calendar event by its UID, including full description, attendees, and recurrence rules.',
     inputSchema: z.object({
         uid: z.string().describe('The UID of the event'),
@@ -854,6 +875,13 @@ export const getEventTool = {
  */
 export const createEventTool = {
     name: 'create_event',
+    title: 'Create Calendar Event',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
     description: 'Create a new calendar event in Nextcloud with date/time, location, description, attendees, and optional recurrence.',
     inputSchema: z.object({
         summary: z.string().describe('The event title'),
@@ -1075,6 +1103,13 @@ export const createEventTool = {
  */
 export const updateEventTool = {
     name: 'update_event',
+    title: 'Update Calendar Event',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: "Update an existing calendar event's fields by UID. Uses CalDAV ETag-based optimistic concurrency.",
     inputSchema: z.object({
         uid: z.string().describe('The UID of the event to update'),
@@ -1248,6 +1283,13 @@ export const updateEventTool = {
  */
 export const deleteEventTool = {
     name: 'delete_event',
+    title: 'Delete Calendar Event',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Delete a calendar event from Nextcloud by UID. This action is irreversible.',
     inputSchema: z.object({
         uid: z.string().describe('The UID of the event to delete'),

package/dist/tools/apps/circles.js

@@ -67,6 +67,13 @@ function formatMember(m) {
 // ---------------------------------------------------------------------------
 export const circlesListTool = {
     name: 'circles_list',
+    title: 'List Circles',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'List all circles/teams accessible to the current user. Returns circle IDs, names, owners, and configuration.',
     inputSchema: z.object({
         limit: z.number().optional().describe('Maximum number of circles to return'),
@@ -95,6 +102,13 @@ export const circlesListTool = {
 // ---------------------------------------------------------------------------
 export const circlesGetTool = {
     name: 'circles_get',
+    title: 'Get Circle',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Get detailed information about a specific circle/team, including its description, owner, and configuration flags.',
     inputSchema: z.object({
         circleId: z.string().describe('The circle ID to retrieve'),
@@ -128,6 +142,13 @@ export const circlesGetTool = {
 // ---------------------------------------------------------------------------
 export const circlesCreateTool = {
     name: 'circles_create',
+    title: 'Create Circle',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
     description: 'Create a new circle/team. The current user becomes the owner. Set personal=true for a private circle only visible to the owner.',
     inputSchema: z.object({
         name: z.string().describe('Name for the new circle'),
@@ -161,6 +182,13 @@ export const circlesCreateTool = {
 // ---------------------------------------------------------------------------
 export const circlesDeleteTool = {
     name: 'circles_delete',
+    title: 'Delete Circle',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Delete a circle/team. Requires owner privileges.',
     inputSchema: z.object({
         circleId: z.string().describe('The circle ID to delete'),
@@ -182,6 +210,13 @@ export const circlesDeleteTool = {
 // ---------------------------------------------------------------------------
 export const circlesListMembersTool = {
     name: 'circles_list_members',
+    title: 'List Circle Members',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'List all members of a circle/team. Returns member IDs (needed for removal), user IDs, types, and permission levels.',
     inputSchema: z.object({
         circleId: z.string().describe('The circle ID to list members for'),
@@ -204,6 +239,13 @@ export const circlesListMembersTool = {
 // ---------------------------------------------------------------------------
 export const circlesAddMemberTool = {
     name: 'circles_add_member',
+    title: 'Add Circle Member',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Add a member to a circle/team. Requires moderator privileges or higher. Member type: 1=user (default), 2=group, 4=mail, 16=circle.',
     inputSchema: z.object({
         circleId: z.string().describe('The circle ID to add the member to'),
@@ -232,6 +274,13 @@ export const circlesAddMemberTool = {
 // ---------------------------------------------------------------------------
 export const circlesRemoveMemberTool = {
     name: 'circles_remove_member',
+    title: 'Remove Circle Member',
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Remove a member from a circle/team. Use circles_list_members to get the memberId. Requires moderator privileges or higher.',
     inputSchema: z.object({
         circleId: z.string().describe('The circle ID to remove the member from'),
@@ -252,6 +301,13 @@ export const circlesRemoveMemberTool = {
 // ---------------------------------------------------------------------------
 export const circlesSearchTool = {
     name: 'circles_search',
+    title: 'Search Circles',
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: 'Search for circles/teams by name.',
     inputSchema: z.object({
         term: z.string().describe('Search term to match against circle names'),