Skip to main content

​
MCP Tool Annotations CLI

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

​
Commands Overview

CommandDescription
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

OptionDescription
--jsonOutput 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

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

​
See Also