feat(tools): add safety annotations for tool compliance (#579)

Per feedback from Anthropic on MCP Safety Guidelines and policy to be in
their registry, adding the tool safety annotations as follows -

* Add readOnlyHint: true to tools that only read data without
modification (such as authentication checks, listing operations,
searching, and documentation retrieval)
* Add destructiveHint: false to tools that perform only additive updates
(such as creating teams, projects, and DSNs)
* Explicitly set destructiveHint: true for tools that modify or update
existing data (such as update operations)
* Consider adding idempotentHint: true for operations that can be safely
repeated with the same arguments

Ensure all 19 tools have appropriate safety annotations

- Introduced safety annotations to all tools for MCP directory
compliance, including `readOnlyHint`, `destructiveHint`,
`idempotentHint`, and `openWorldHint`.
- Updated relevant tools to include these annotations, ensuring clear
communication of tool behavior and data modification capabilities.
- Added documentation on required annotations and their usage patterns
to `docs/adding-tools.mdc`.

---------

Co-authored-by: Claude Code <noreply@anthropic.com>

Author: codyde

docs/adding-tools.mdc

@@ -59,12 +59,51 @@ export default defineTool({
     regionUrl: z.string().optional().describe("Optional region URL"),
     yourParam: z.string().describe("What values are expected"),
   },
+  annotations: {
+    readOnlyHint: true,
+    openWorldHint: true,
+  },
   async handler(params, context: ServerContext) {
     // Implementation here
   },
 });
 ```
 
+### Safety Annotations
+
+**REQUIRED**: All tools must include safety annotations for MCP directory compliance.
+
+**Available annotations:**
+- `readOnlyHint` (boolean): Tool doesn't modify data
+- `destructiveHint` (boolean): Tool may modify/delete existing data
+- `idempotentHint` (boolean): Repeated calls with same arguments have no additional effect
+- `openWorldHint` (boolean): Tool interacts with external services (default: true for API calls)
+
+**Annotation patterns:**
+
+```typescript
+// Read-only tools (queries, lists, searches)
+annotations: {
+  readOnlyHint: true,
+  openWorldHint: true,
+}
+
+// Create tools (additive, non-destructive)
+annotations: {
+  readOnlyHint: false,
+  destructiveHint: false,
+  openWorldHint: true,
+}
+
+// Update tools (modify existing data)
+annotations: {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: true,  // Same update twice = same result
+  openWorldHint: true,
+}
+```
+
 ### Writing LLM-Friendly Descriptions
 
 Critical for LLM success:

packages/mcp-server/src/server.ts

@@ -339,6 +339,7 @@ export async function configureServer({
       tool.name,
       tool.description,
       modifiedInputSchema,
+      tool.annotations,
       async (
         params: any,
         extra: RequestHandlerExtra<ServerRequest, ServerNotification>,

packages/mcp-server/src/tools/analyze-issue-with-seer.ts

@@ -77,6 +77,11 @@ export default defineTool({
       .describe("Optional custom instruction for the AI analysis")
       .optional(),
   },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
   async handler(params, context: ServerContext) {
     const apiService = apiServiceFromContext(context, {
       regionUrl: params.regionUrl,

packages/mcp-server/src/tools/create-dsn.ts

@@ -45,6 +45,11 @@ export default defineTool({
       .trim()
       .describe("The name of the DSN to create, for example 'Production'."),
   },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
   async handler(params, context: ServerContext) {
     const apiService = apiServiceFromContext(context, {
       regionUrl: params.regionUrl,

packages/mcp-server/src/tools/create-project.ts

@@ -52,6 +52,11 @@ export default defineTool({
       ),
     platform: ParamPlatform.optional(),
   },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
   async handler(params, context: ServerContext) {
     const apiService = apiServiceFromContext(context, {
       regionUrl: params.regionUrl,

packages/mcp-server/src/tools/create-team.ts

@@ -34,6 +34,11 @@ export default defineTool({
     regionUrl: ParamRegionUrl.optional(),
     name: z.string().trim().describe("The name of the team to create."),
   },
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
   async handler(params, context: ServerContext) {
     const apiService = apiServiceFromContext(context, {
       regionUrl: params.regionUrl,

packages/mcp-server/src/tools/find-dsns.ts

@@ -27,6 +27,10 @@ export default defineTool({
     regionUrl: ParamRegionUrl.optional(),
     projectSlug: ParamProjectSlug,
   },
+  annotations: {
+    readOnlyHint: true,
+    openWorldHint: true,
+  },
   async handler(params, context: ServerContext) {
     const apiService = apiServiceFromContext(context, {
       regionUrl: params.regionUrl,

packages/mcp-server/src/tools/find-organizations.ts

@@ -21,6 +21,10 @@ export default defineTool({
   inputSchema: {
     query: ParamSearchQuery.optional(),
   },
+  annotations: {
+    readOnlyHint: true,
+    openWorldHint: true,
+  },
   async handler(params, context: ServerContext) {
     // User data endpoints (like /users/me/regions/) should never use regionUrl
     // as they must always query the main API server, not region-specific servers

packages/mcp-server/src/tools/find-projects.ts

@@ -29,6 +29,10 @@ export default defineTool({
     regionUrl: ParamRegionUrl.optional(),
     query: ParamSearchQuery.optional(),
   },
+  annotations: {
+    readOnlyHint: true,
+    openWorldHint: true,
+  },
   async handler(params, context: ServerContext) {
     const apiService = apiServiceFromContext(context, {
       regionUrl: params.regionUrl,

packages/mcp-server/src/tools/find-releases.ts

@@ -48,6 +48,10 @@ export default defineTool({
       .describe("Search for versions which contain the provided string.")
       .optional(),
   },
+  annotations: {
+    readOnlyHint: true,
+    openWorldHint: true,
+  },
   async handler(params, context: ServerContext) {
     const apiService = apiServiceFromContext(context, {
       regionUrl: params.regionUrl,