Tool Search

Name: Tool Search
Author: oimiragieo

oimiragieo/agent-studio

57 installs
36 repo stars
Updated July 14, 2026
oimiragieo/agent-studio

Helps with ai & agent building tasks.

About

tool-search is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted development.

tool-search
AI & Agent Building
AI-coding skill

Tool Search by the numbers

57 all-time installs (skills.sh)
Ranked #6,669 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
Data as of Aug 4, 2026 (Skillselion catalog sync)

npx skills add https://github.com/oimiragieo/agent-studio --skill tool-search

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/oimiragieo/agent-studio/tool-search.svg)](https://skillselion.com/skills/oimiragieo/agent-studio/tool-search)

Installs	57
repo stars	★ 36
Last updated	July 14, 2026
Repository	oimiragieo/agent-studio ↗

What it does

Helps with ai & agent building tasks.

Files

SKILL.mdMarkdownGitHub ↗

References (archive): SCAFFOLD_SKILLS_ARCHIVE_MAP.md — embedding/semantic tool discovery from everything-claude-code backend-patterns, tdd-workflow.

Tool Search Skill

Identity

Tool Search - Provides semantic tool discovery using embeddings to scale from dozens to thousands of tools with 90%+ context reduction.

Capabilities

Semantic Tool Search: Find relevant tools based on task context
Embedding-Based Matching: Use embeddings for accurate tool discovery
On-Demand Loading: Load tools only when needed
Context Efficiency: 90%+ reduction in tool definition tokens

The Problem

Traditional tool loading:

All tools loaded upfront
58 tools = ~55K tokens
Context fills quickly
Hard to scale beyond ~100 tools

The Solution

Tool Search with Embeddings:

Only Tool Search Tool loaded initially (~500 tokens)
Tools discovered on-demand via semantic search
3-5 relevant tools loaded per search (~3K tokens)
Total: ~8.7K tokens vs. ~77K traditional (85% reduction)

How It Works

1. Initial State: Only Tool Search Tool + critical tools loaded 2. Tool Discovery: Agent searches for tools based on task 3. Semantic Matching: Embeddings match tools to task context 4. Tool Expansion: Matching tools expanded into full definitions 5. Tool Use: Agent uses discovered tools

Configuration

MCP Configuration (`.claude/.mcp.json`)

{
  "betaFeatures": ["advanced-tool-use-2025-11-20"],
  "toolSearch": {
    "enabled": true,
    "autoEnableThreshold": 20,
    "defaultDeferLoading": true
  },
  "mcpServers": {
    "repo": {
      "deferLoading": true,
      "alwaysLoadTools": ["search_code", "read_file"]
    },
    "github": {
      "deferLoading": true,
      "alwaysLoadTools": ["create_pull_request", "get_issue"]
    }
  }
}

Always Load Critical Tools

Keep 3-5 most-used tools always loaded:

Core file operations: read_file, write_file, search_code
Essential integrations: create_pull_request, get_issue
Frequently used: take_screenshot, navigate_page

Usage Patterns

When to Use Tool Search

Most Beneficial When:

Tool definitions consuming >10K tokens
Tool library has 10+ tools
Experiencing tool selection accuracy issues
Building MCP-powered systems with multiple servers

Less Beneficial When:

Small tool library (<10 tools)
All tools used frequently in every session
Tool definitions are compact

Tool Discovery

Agent Workflow:

1. Agent needs capability (e.g., "create a pull request") 2. Agent searches: "github pull request creation" 3. Tool Search returns: create_pull_request tool 4. Tool expanded into full definition 5. Agent uses tool

Example:

User: "Create a pull request for my changes"

Agent searches: "github pull request creation"
Tool Search finds: create_pull_request tool
Tool loaded and used

Best Practices

1. Clear Tool Names and Descriptions

Good:

{
  "name": "search_customer_orders",
  "description": "Search for customer orders by date range, status, or total amount. Returns order details including items, shipping, and payment info."
}

Bad:

{
  "name": "query_db_orders",
  "description": "Execute order query"
}

2. System Prompt Guidance

Add guidance in agent prompts:

You have access to tools for Slack messaging, Google Drive file management,
Jira ticket tracking, and GitHub repository operations. Use the tool search
to find specific capabilities when needed.

3. Keep Critical Tools Always Loaded

Don't defer loading for:

Core file operations
Essential integrations
Frequently used tools

4. Monitor Tool Usage

Track which tools are discovered:

Most searched tools
Tool discovery patterns
Context savings achieved

Implementation

Embedding-Based Tool Search

The tool search uses embeddings to match tools to queries:

1. Tool Indexing: Create embeddings for all tool definitions 2. Query Embedding: Create embedding for user query 3. Similarity Search: Find tools with similar embeddings 4. Tool Expansion: Load matching tools into context

Tool Search Tool

The Tool Search Tool itself:

Searches tool library semantically
Returns relevant tools based on query
Expands tools into full definitions
Maintains tool index

Benefits

Context Efficiency

85% reduction in tool definition tokens
52.5% total context (down from 87%)
Within optimal range (60-70% target)

Improved Accuracy

11% improvement in tool selection accuracy
79.5% → 88.1% (Opus 4.5)
Better tool matching for complex queries

Scalability

Scales to thousands of tools
No context limit concerns
Dynamic tool discovery

Examples

Example 1: GitHub Operations

User: "Create a pull request"

Agent workflow:
1. Searches: "github pull request creation"
2. Tool Search finds: create_pull_request tool
3. Tool loaded (3K tokens)
4. Agent uses tool
5. Total context: ~8.7K tokens (vs. 55K traditional)

Example 2: File Operations

User: "Search for authentication code"

Agent workflow:
1. Searches: "code search file operations"
2. Tool Search finds: search_code, read_file tools
3. Tools loaded (5K tokens)
4. Agent uses tools

Example 3: Multiple Integrations

User: "Check Slack messages and create Jira ticket"

Agent workflow:
1. Searches: "slack message reading"
2. Tool Search finds: read_slack_message tool
3. Searches: "jira ticket creation"
4. Tool Search finds: create_jira_ticket tool
5. Both tools loaded (6K tokens total)

Integration

With MCP Servers

Tool search works with MCP servers:

GitHub MCP: 35 tools → 3-5 loaded on-demand
Slack MCP: 11 tools → 2-3 loaded on-demand
Custom MCPs: Any number of tools → Loaded as needed

With Agent System

All agents benefit from tool search:

Reduced context usage
Better tool selection
Scalable tool libraries

Troubleshooting

Tools Not Found

Check tool names and descriptions are clear
Verify tool search is enabled
Review search queries
Check tool index is up to date

Context Still High

Verify deferLoading is enabled
Check alwaysLoadTools list (should be minimal)
Review tool definitions (may be too verbose)
Monitor actual tool usage

Tool Selection Issues

Improve tool descriptions
Add more context to search queries
Review tool naming conventions
Check embedding quality

Integration with Programmatic Tool Calling (PTC)

Tool Search works excellently with Programmatic Tool Calling:

1. Tool Search finds relevant tools (on-demand loading) 2. PTC orchestrates tools efficiently (reduced context) 3. Result: Optimal tool usage with minimal token consumption

Example Workflow:

# Tool Search finds tools
tools = search_tools("github issue management")

# PTC orchestrates multiple tool calls
team = await get_team_members("engineering")
issues = await asyncio.gather(*[
    get_issue(member["github_username"]) for member in team
])
# Only final results in context, not all intermediate data

See PTC Patterns Guide for comprehensive PTC documentation.

References

<examples> <usage_example> Example Commands:

# Search for git-related tools
node .claude/tools/tool_search.mjs --query "git"

# Search for database tools
node .claude/tools/tool_search.mjs --query "database" --limit 3

# Search for testing tools
node .claude/tools/tool_search.mjs --query "testing"

</usage_example> </examples>

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

New pattern -> .claude/context/memory/learnings.md
Issue found -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

#!/usr/bin/env node

/**
 * tool-search - Post-Execute Hook
 * Runs after the skill executes for cleanup, logging, or follow-up actions.
 */

const fs = require('fs');
const path = require('path');
const { safeParseJSON } = require('../../../lib/utils/safe-json.cjs');

// Parse hook input
const result = safeParseJSON(process.argv[2] || '{}');

console.log('📝 [TOOL-SEARCH] Post-execute processing...');

/**
 * Process execution result
 */
function processResult(_result) {
  // TODO: Add your post-processing logic here

  return { success: true };
}

// Run post-processing
const outcome = processResult(result);

if (outcome.success) {
  console.log('✅ [TOOL-SEARCH] Post-processing complete');
  process.exit(0);
} else {
  console.error('⚠️  [TOOL-SEARCH] Post-processing had issues');
  process.exit(0);
}

#!/usr/bin/env node

/**
 * tool-search - Pre-Execute Hook
 * Runs before the skill executes to validate input or prepare context.
 */

const fs = require('fs');
const path = require('path');
const { safeParseJSON } = require('../../../lib/utils/safe-json.cjs');

// Parse hook input
const input = safeParseJSON(process.argv[2] || '{}');

console.log('🔍 [TOOL-SEARCH] Pre-execute validation...');

/**
 * Validate input before execution
 */
function validateInput(_input) {
  const errors = [];

  // TODO: Add your validation logic here

  return errors;
}

// Run validation
const errors = validateInput(input);

if (errors.length > 0) {
  console.error('❌ Validation failed:');
  errors.forEach(e => console.error('   - ' + e));
  process.exit(1);
}

console.log('✅ [TOOL-SEARCH] Validation passed');
process.exit(0);

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "tool-search Input Schema",
  "description": "Input validation schema for tool-search skill",
  "type": "object",
  "required": [],
  "properties": {},
  "additionalProperties": true
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "tool-search Output Schema",
  "description": "Output validation schema for tool-search skill",
  "type": "object",
  "required": ["success"],
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the skill executed successfully"
    },
    "result": {
      "type": "object",
      "description": "The skill execution result",
      "additionalProperties": true
    },
    "error": {
      "type": "string",
      "description": "Error message if execution failed"
    }
  },
  "additionalProperties": true
}

#!/usr/bin/env node
'use strict';

const fs = require('node:fs');
const path = require('node:path');

function findProjectRoot(start = __dirname) {
  let dir = start;
  while (dir !== path.parse(dir).root) {
    if (fs.existsSync(path.join(dir, '.claude', 'CLAUDE.md'))) return dir;
    dir = path.dirname(dir);
  }
  return process.cwd();
}

function parseArgs(argv) {
  const options = {};
  const text = [];
  for (let i = 0; i < argv.length; i++) {
    const arg = argv[i];
    if (!arg.startsWith('--')) {
      text.push(arg);
      continue;
    }
    const key = arg.slice(2);
    const next = argv[i + 1];
    const hasValue = next && !next.startsWith('--');
    options[key] = hasValue ? argv[++i] : true;
  }
  return { options, query: text.join(' ').trim() };
}

function loadManifest(projectRoot) {
  const manifestPath = path.join(projectRoot, '.claude', 'config', 'tool-manifest.json');
  if (!fs.existsSync(manifestPath)) {
    throw new Error(`tool-manifest missing at ${manifestPath}`);
  }
  return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
}

function asSearchDocs(manifest) {
  const docs = [];
  for (const tool of manifest?.tools?.core || []) {
    docs.push({
      name: tool.name,
      category: 'core',
      description: tool.description || '',
      tags: [tool.server, tool.scope].filter(Boolean).join(' '),
    });
  }
  for (const tool of manifest?.tools?.mcp || []) {
    docs.push({
      name: tool.name,
      category: `mcp:${tool.server || 'unknown'}`,
      description: tool.description || '',
      tags: [tool.server, tool.connector, tool.scope].filter(Boolean).join(' '),
    });
  }
  return docs;
}

function tokenize(text) {
  return String(text || '')
    .toLowerCase()
    .split(/[^a-z0-9_:-]+/)
    .map(token => token.trim())
    .filter(Boolean);
}

function scoreDoc(doc, queryTokens) {
  if (queryTokens.length === 0) return 0;
  const haystack = `${doc.name} ${doc.description} ${doc.tags}`.toLowerCase();
  let score = 0;
  for (const token of queryTokens) {
    if (doc.name.toLowerCase() === token) score += 6;
    else if (doc.name.toLowerCase().includes(token)) score += 4;
    else if (haystack.includes(token)) score += 1;
  }
  return score;
}

function searchTools(query, docs, limit = 8) {
  const queryTokens = tokenize(query);
  return docs
    .map(doc => ({ ...doc, score: scoreDoc(doc, queryTokens) }))
    .filter(doc => doc.score > 0)
    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
    .slice(0, limit);
}

function main(input = {}) {
  const query = String(input.query || '').trim();
  const limit = Number.isFinite(Number(input.limit)) ? Math.max(1, Number(input.limit)) : 8;
  const projectRoot = input.projectRoot || findProjectRoot();

  if (!query) {
    return { ok: false, error: 'query is required' };
  }

  const manifest = loadManifest(projectRoot);
  const docs = asSearchDocs(manifest);
  const results = searchTools(query, docs, limit);
  return {
    ok: true,
    query,
    totalTools: docs.length,
    returned: results.length,
    results,
  };
}

if (require.main === module) {
  const { options, query } = parseArgs(process.argv.slice(2));
  if (options.help) {
    console.log(`
tool-search

Usage:
  node main.cjs <query> [--limit 8]
`);
    process.exit(0);
  }
  const result = main({
    query: options.query || query,
    limit: options.limit,
  });
  if (!result.ok) {
    console.error(result.error);
    process.exit(1);
  }
  console.log(JSON.stringify(result, null, 2));
}

module.exports = {
  parseArgs,
  loadManifest,
  asSearchDocs,
  searchTools,
  main,
};