本资料是 aic-mcp-server 项目新增 MCP 工具的实现约定。用途：在创建或修改工具时，规定其结构、响应格式、annotations 与注册方式。
主要能力与用法：工具文件放在 src/tools/<category>/myNewTool.ts，需从 zod 引入 z，并从 ../../utils/apiHelpers.js 引入 makeAuthenticatedRequest、createToolResponse，从 ../../utils/responseHelpers.js 引入 formatSuccess。模块级定义 SCOPES 常量，并在工具对象与请求调用中复用。工具对象包含 name、title、description、scopes、annotations、inputSchema 及异步 toolFunction。请求使用 makeAuthenticatedRequest(url, SCOPES, { method })，URL 拼接自环境变量 AIC_BASE_URL。返回通过 createToolResponse(formatSuccess(data, response)) 生成。
响应格式化：formatSuccess(data, response) 可接受对象或字符串，内部处理 JSON 序列化；应传入 response 对象以自动附加 x-forgerock-transactionid 事务 ID，便于追踪工具调用。对于返回 204 的写操作（如 DELETE、部分 PUT），需手动从 response.headers.get('x-forgerock-transactionid') 提取事务 ID。
Annotations：每个工具应有 annotations 对象，向 MCP 客户端提示行为。readOnlyHint 默认 false，destructiveHint 默认 true（仅在 readOnlyHint 为 false 时有效），idempotentHint 默认 false，openWorldHint 默认 true。常用组合：只读为 { readOnlyHint: true, openWorldHint: true }；创建为 { openWorldHint: true }；幂等更新加 idempotentHint;删除加 destructiveHint。
注册与新增分类：在 src/tools/<category>/index.ts 中导出工具，toolHelpers.ts 通过 Object.values() 自动收集并注册。若新增分类，需创建目录与 index.ts，并在 src/utils/toolHelpers.ts 的 getAllTools() 中导入并展开；若分类需要浏览器认证（如 AM 工具），则放入 !isDockerMode 守卫内。命名约定：导出名为 <toolName>Tool；路径中的用户 ID 使用 validationHelpers 的 safePathSegmentSchema，realm 参数使用 z.enum(REALMS)。
限制：资料未提供具体安装命令、依赖版本或完整示例代码；部分代码在原文中可能被截断，缺失事实暂未提供。