> ## 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 Search CLI

> CLI commands for searching and filtering MCP tools

# MCP Tool Search CLI

Command-line interface for searching and filtering MCP server tools.

## Command Overview

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp tools search [query] [options]
```

## Options

| Option              | Description                        | Example                  |
| ------------------- | ---------------------------------- | ------------------------ |
| `<query>`           | Text to search in name/description | `"memory"`               |
| `--category <cat>`  | Filter by category                 | `--category file`        |
| `--tag <tag>`       | Filter by tag (repeatable)         | `--tag search --tag web` |
| `--read-only`       | Show only read-only tools          | `--read-only`            |
| `--json`            | Output in JSON format              | `--json`                 |
| `--limit <n>`       | Max results per page               | `--limit 10`             |
| `--cursor <cursor>` | Pagination cursor                  | `--cursor NTA`           |

## Basic Usage

### Search by Query

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Search for tools containing "memory"
praisonai mcp tools search "memory"
```

**Output:**

```
Search Results (2 of 2):

  • memory.show [read-only]
    Show memory contents

  • memory.clear [destructive]
    Clear memory contents
```

### Search by Category

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Find all file-related tools
praisonai mcp tools search --category file
```

**Output:**

```
Search Results (3 of 3):

  • file.read [read-only]
    Read file contents

  • file.write [destructive]
    Write to file

  • file.delete [destructive]
    Delete a file
```

### Search Read-Only Tools

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Find safe tools that don't modify state
praisonai mcp tools search --read-only
```

**Output:**

```
Search Results (5 of 5):

  • memory.show [read-only]
    Show memory contents

  • file.read [read-only]
    Read file contents

  • web.search [read-only]
    Search the web
  ...
```

### Combined Filters

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Find read-only tools in memory category
praisonai mcp tools search --category memory --read-only

# Search with query and category filter
praisonai mcp tools search "show" --category memory
```

## JSON Output

### Basic JSON

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

**Output:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "tools": [
    {
      "name": "memory.show",
      "description": "Show memory contents",
      "inputSchema": {"type": "object"},
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false
      }
    }
  ],
  "total": 1
}
```

### JSON with Pagination

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp tools search --json --limit 5
```

**Output:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "tools": [...],
  "total": 25,
  "nextCursor": "NQ"
}
```

## Pagination

### First Page

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp tools search --limit 10
```

### Next Page

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp tools search --limit 10 --cursor NTA
```

### Iterate All Pages

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
#!/bin/bash
# Search and iterate through all pages

query="$1"
cursor=""

while true; do
    if [ -z "$cursor" ]; then
        result=$(praisonai mcp tools search "$query" --json --limit 10)
    else
        result=$(praisonai mcp tools search "$query" --json --limit 10 --cursor "$cursor")
    fi
    
    # Process results
    echo "$result" | jq '.tools[].name'
    
    # Get next cursor
    cursor=$(echo "$result" | jq -r '.nextCursor // empty')
    
    if [ -z "$cursor" ]; then
        break
    fi
done
```

## Examples

### Find Destructive Tools

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List tools that may modify data (not read-only)
praisonai mcp tools search --json | \
  jq '.tools[] | select(.annotations.readOnlyHint != true) | .name'
```

### Export Search Results

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Export memory tools to file
praisonai mcp tools search "memory" --json > memory_tools.json
```

### Count Results

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Count read-only tools
praisonai mcp tools search --read-only --json | jq '.total'
```

### Search with jq Processing

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Get names only
praisonai mcp tools search "file" --json | jq -r '.tools[].name'

# Get tools with descriptions
praisonai mcp tools search --json | \
  jq '.tools[] | "\(.name): \(.description)"'

# Filter by annotation in post-processing
praisonai mcp tools search --json | \
  jq '.tools[] | select(.annotations.idempotentHint == true)'
```

### Build Tool Inventory

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
#!/bin/bash
# Create tool inventory by category

echo "# Tool Inventory"
echo ""

for category in memory file web config; do
    count=$(praisonai mcp tools search --category "$category" --json 2>/dev/null | jq '.total // 0')
    echo "## $category: $count tools"
    
    if [ "$count" -gt 0 ]; then
        praisonai mcp tools search --category "$category" --json | \
          jq -r '.tools[] | "- \(.name)"'
    fi
    echo ""
done
```

## Error Handling

### No Results

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp tools search "nonexistent"
# No tools found matching your criteria
# Exit code: 0
```

### Invalid Cursor

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai mcp tools search --cursor "invalid!!!"
# Error: Search error: Invalid cursor
# Exit code: 1
```

## Exit Codes

| Code | Meaning                        |
| ---- | ------------------------------ |
| 0    | Success (even with no results) |
| 1    | Error (invalid cursor, etc.)   |

## Comparison with list-tools

| Feature          | `list-tools` | `tools search` |
| ---------------- | ------------ | -------------- |
| List all tools   | ✓            | ✓              |
| Query filter     | ✗            | ✓              |
| Category filter  | ✗            | ✓              |
| Tag filter       | ✗            | ✓              |
| Read-only filter | ✗            | ✓              |
| Pagination       | ✓            | ✓              |
| JSON output      | ✓            | ✓              |
| Total count      | ✗            | ✓              |

Use `list-tools` for simple listing, `tools search` for filtering.

## See Also

* [MCP Tool Search Module](/docs/mcp/mcp-tool-search) - Code-based search usage
* [MCP Pagination CLI](/docs/cli/mcp-pagination) - Pagination details
* [MCP Tool Annotations CLI](/docs/cli/mcp-tool-annotations) - View tool annotations
* [MCP CLI Overview](/docs/cli/mcp) - All MCP CLI commands