Skip to main content

​
MCP Tool Search CLI

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

​
Command Overview

praisonai mcp tools search [query] [options]

​
Options

OptionDescriptionExample
<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-onlyShow only read-only tools--read-only
--jsonOutput in JSON format--json
--limit <n>Max results per page--limit 10
--cursor <cursor>Pagination cursor--cursor NTA

​
Basic Usage

​
Search by Query

# 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

# 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

# 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

# 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

praisonai mcp tools search "memory" --json
Output: 
{
  "tools": [
    {
      "name": "memory.show",
      "description": "Show memory contents",
      "inputSchema": {"type": "object"},
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false
      }
    }
  ],
  "total": 1
}

​
JSON with Pagination

praisonai mcp tools search --json --limit 5
Output: 
{
  "tools": [...],
  "total": 25,
  "nextCursor": "NQ"
}

​
Pagination

​
First Page

praisonai mcp tools search --limit 10

​
Next Page

praisonai mcp tools search --limit 10 --cursor NTA

​
Iterate All Pages

#!/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

# List tools that may modify data (not read-only)
praisonai mcp tools search --json | \
  jq '.tools[] | select(.annotations.readOnlyHint != true) | .name'

​
Export Search Results

# Export memory tools to file
praisonai mcp tools search "memory" --json > memory_tools.json

​
Count Results

# Count read-only tools
praisonai mcp tools search --read-only --json | jq '.total'

​
Search with jq Processing

# 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

#!/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

praisonai mcp tools search "nonexistent"
# No tools found matching your criteria
# Exit code: 0

​
Invalid Cursor

praisonai mcp tools search --cursor "invalid!!!"
# Error: Search error: Invalid cursor
# Exit code: 1

​
Exit Codes

CodeMeaning
0Success (even with no results)
1Error (invalid cursor, etc.)

​
Comparison with list-tools

Featurelist-toolstools 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