MCP Tool Behavior Declarator

CodingBeginner

Adds behavior annotations to MCP tool definitions per the 2025-06-18 spec. Clients use these to adjust UI presentation and safety gating.

Trigger/mcp-tool-attr

Frequencyper tool

MCP Server Author? Run /mcp-tool-attr to annotate all tools for safer client behavior

Security Engineer? Ensure destructive tools are properly flagged for UI gating

MCPTool BehaviorSafetyUX

How It Works

/mcp-tool-attr [server-dir] run

↓

Phase 1: scan and classify tools

tool-scan

List all registered tools

classify

Auto-classify read/write/destructive

annotate

Add behavior attributes

↓

Generate behavior summary table

↓

✓ All tools annotated with behavior attributes

Skill Code

# MCP Tool Behavior Declarator
## Trigger: /mcp-tool-attr [server-directory]

When invoked:

1. Scan tools and add behavior annotations:
```typescript
server.tool("list-files", {
  description: "List files in a directory",
  annotations: {
    readOnlyHint: true,        // Does not modify state
    destructiveHint: false,    // Cannot destroy data
    idempotentHint: true,      // Safe to retry
    openWorldHint: false,      // No external side effects
  },
  inputSchema: { /* ... */ }
}, handler);

server.tool("delete-record", {
  description: "Permanently delete a database record",
  annotations: {
    readOnlyHint: false,
    destructiveHint: true,     // Irreversible action
    idempotentHint: true,      // Deleting twice = same result
    openWorldHint: false,
  },
  inputSchema: { /* ... */ }
}, handler);

server.tool("send-email", {
  description: "Send email to a recipient",
  annotations: {
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: false,     // Sending twice = two emails
    openWorldHint: true,       // External side effect (email sent)
  },
  inputSchema: { /* ... */ }
}, handler);
```

2. Behavior classification guide:
| Attribute | true | false |
|-----------|------|-------|
| readOnlyHint | Queries, listings, searches | Create, update, delete |
| destructiveHint | Delete, drop, purge, overwrite | Create, read, append |
| idempotentHint | GET-like, upsert, delete | POST-like, send, increment |
| openWorldHint | Email, API call, webhook | Local DB, file system |

3. Client behavior expectations:
 - readOnly: may auto-approve without user confirmation
 - destructive: should show confirmation dialog
 - idempotent: safe to retry on network errors
 - openWorld: warn about external side effects

Copy and paste into your CLAUDE.md to start using immediately.

How MCP Tool Behavior Declarator Works

MCP Tool Behavior Declarator scans all tools in your server directory, auto-classifies each as readOnly, destructive, idempotent, or openWorld, and adds annotations objects. Clients use these attributes to determine UI behavior — showing confirmation dialogs for destructive tools, auto-approving read-only ones, and optimizing retries for idempotent tools.

When to Use MCP Tool Behavior Declarator

Essential when your MCP server has multiple tools with varying safety levels. Explicitly declaring behavior attributes enables clients to apply appropriate UI gating and retry strategies.

Key Strengths

Auto-classification across four behavior attributes
Destructive tools automatically gated with confirmation dialogs
Read-only tools can run without user approval
Idempotent marking enables safe network error retries

Same Category

Coding View All

Smart Commit

Analyzes changes and auto-generates meaningful commit messages.

Code Review

Analyzes code changes and provides severity-based review feedback.

Bug Hunter

Analyzes error messages and traces the root cause in the codebase.

Popular in Other Categories

Session Summary

WorkflowAutomatically summarizes changes and next steps at the end of a work session.

CLAUDE.md Builder

ProductivityAnalyzes your project and auto-generates an optimized CLAUDE.md.

API Design Assistant

DocumentationDesigns RESTful APIs and auto-generates docs and type definitions.