MCP Tool Annotations CLI

CLI commands for viewing tool annotations and metadata

MCP Tool Annotations CLI

Command-line interface for viewing MCP tool annotations and behavioral hints.

Commands Overview

Command	Description
praisonai mcp tools info <name>	Get detailed tool information including annotations
praisonai mcp tools schema <name>	Get full JSON schema with annotations

Tools Info Command

Basic Usage

praisonai mcp tools info praisonai.workflow.run

Output:

Tool: praisonai.workflow.run

Description: Execute a PraisonAI workflow from YAML definition

Annotations:
  • readOnlyHint: False
  • destructiveHint: True
  • idempotentHint: False
  • openWorldHint: True
  • category: workflow
  • tags: ai, automation, workflow

Parameters:
  • workflow: string (required)
    Path to workflow YAML file

Options

Option	Description
--json	Output in JSON format

JSON Output

praisonai mcp tools info praisonai.memory.show --json

Output:

{
  "name": "praisonai.memory.show",
  "description": "Show memory contents",
  "inputSchema": {
    "type": "object",
    "properties": {
      "session_id": {"type": "string"}
    }
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  }
}

Tools Schema Command

Basic Usage

praisonai mcp tools schema praisonai.file.read

Output:

{
  "name": "praisonai.file.read",
  "description": "Read file contents",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "File path to read"
      }
    },
    "required": ["path"]
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  }
}

Understanding Annotations

readOnlyHint

# Find read-only tools
praisonai mcp tools search --read-only --json | jq '.tools[].name'

Read-only tools (readOnlyHint: true):

• Only retrieve/display data
• Don’t modify any state
• Safe to call without side effects

destructiveHint

Tools with destructiveHint: true:

• May delete or modify data irreversibly
• Require user confirmation in some clients
• Examples: file.delete, database.drop

idempotentHint

Tools with idempotentHint: true:

• Safe to retry on failure
• Multiple calls produce same result
• Examples: config.set, cache.invalidate

openWorldHint

Tools with openWorldHint: false:

• Only interact with local/internal systems
• Don’t make network requests
• Examples: memory.show, session.get

Examples

Check if Tool is Safe

#!/bin/bash
# Check if a tool is safe (read-only and non-destructive)

TOOL=$1
INFO=$(praisonai mcp tools info "$TOOL" --json)

READ_ONLY=$(echo "$INFO" | jq '.annotations.readOnlyHint')
DESTRUCTIVE=$(echo "$INFO" | jq '.annotations.destructiveHint')

if [ "$READ_ONLY" = "true" ] && [ "$DESTRUCTIVE" = "false" ]; then
    echo "✓ Tool $TOOL is safe (read-only, non-destructive)"
else
    echo "⚠ Tool $TOOL may modify data"
fi

List All Tool Annotations

# Get annotations for all tools
praisonai mcp list-tools --json | \
  jq '.tools[] | {name: .name, annotations: .annotations}'

Filter by Annotation Type

# List destructive tools
praisonai mcp list-tools --json | \
  jq '.tools[] | select(.annotations.destructiveHint == true) | .name'

# List idempotent tools
praisonai mcp list-tools --json | \
  jq '.tools[] | select(.annotations.idempotentHint == true) | .name'

# List closed-world tools (no external interaction)
praisonai mcp list-tools --json | \
  jq '.tools[] | select(.annotations.openWorldHint == false) | .name'

Export Tool Documentation

#!/bin/bash
# Generate documentation for all tools

echo "# MCP Tools Reference"
echo ""

for tool in $(praisonai mcp list-tools --json | jq -r '.tools[].name'); do
    echo "## $tool"
    echo ""
    praisonai mcp tools info "$tool" --json | jq -r '
        "**Description:** \(.description)\n" +
        "**Read-only:** \(.annotations.readOnlyHint)\n" +
        "**Destructive:** \(.annotations.destructiveHint)\n"
    '
    echo ""
done

Error Handling

Tool Not Found

praisonai mcp tools info nonexistent.tool
# Error: Tool not found: nonexistent.tool
# Exit code: 1

Invalid Tool Name

praisonai mcp tools schema ""
# Error: Tool name required
# Exit code: 1

Exit Codes

Code	Meaning
0	Success
1	Error (tool not found, invalid input)

See Also

• MCP Tool Annotations Module - Code-based annotations usage
• MCP Tool Search CLI - Search tools by annotations
• MCP CLI Overview - All MCP CLI commands