> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp tools info praisonai.memory.show --json
```

**Output:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp tools schema praisonai.file.read
```

**Output:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
#!/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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Get annotations for all tools
praisonai mcp list-tools --json | \
  jq '.tools[] | {name: .name, annotations: .annotations}'
```

### Filter by Annotation Type

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
#!/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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp tools info nonexistent.tool
# Error: Tool not found: nonexistent.tool
# Exit code: 1
```

### Invalid Tool Name

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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](/docs/mcp/mcp-tool-annotations) - Code-based annotations usage
* [MCP Tool Search CLI](/docs/cli/mcp-tool-search) - Search tools by annotations
* [MCP CLI Overview](/docs/cli/mcp) - All MCP CLI commands