Skip to content

refactor: simplify meta tool names to meta_search_tools and meta_execute_tool #86

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mattzcarey merged 12 commits into from
Aug 18, 2025
Merged

refactor: simplify meta tool names to meta_search_tools and meta_execute_tool #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
41c8cbd
refactor: rename meta tool names from meta_tool to meta_search_tools …
ryoppippi Aug 14, 2025
9d447c8
ENG-10831
ryoppippi Aug 14, 2025
38e78b7
refactor: update meta tools references to meta search tools
ryoppippi Aug 14, 2025
f893c84
refactor: simplify meta tool names to meta_search_tools and meta_exec…
ryoppippi Aug 14, 2025
8c04fe1
Merge branch 'main' into rename-meta-tools-to-meta-search-tools
ryoppippi Aug 18, 2025
975c0d5
Update README.md
mattzcarey Aug 18, 2025
b65a668
Update README.md
mattzcarey Aug 18, 2025
a733271
Update README.md
mattzcarey Aug 18, 2025
99f7ee6
Update README.md
mattzcarey Aug 18, 2025
9e2b658
Update README.md
mattzcarey Aug 18, 2025
2421277
filter -> search
ryoppippi Aug 18, 2025
4e820f6
update comments
ryoppippi Aug 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Copy link
Contributor

@mattzcarey mattzcarey Aug 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

naming should be

meta_search_tools
meta_execute_tool

Copy link
Member Author

@ryoppippi ryoppippi Aug 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh okay so meta_filter_relevant_tools to meta_search_tools ??
@mattzcarey

Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,7 @@ Meta tools enable dynamic tool discovery and execution, allowing AI agents to se
#### How Meta Tools Work

Meta tools provide two core capabilities:
1. **Tool Discovery** (`meta_filter_relevant_tools`): Search for tools using natural language queries
1. **Tool Discovery** (`meta_search_tools`): Search for tools using natural language queries
2. **Tool Execution** (`meta_execute_tool`): Execute discovered tools dynamically

The tool discovery uses Orama's BM25 algorithm for relevance ranking, providing high-quality search results based on tool names, descriptions, and categories.
Expand Down Expand Up @@ -274,7 +274,7 @@ const { text } = await generateText({

```typescript
// Step 1: Discover relevant tools
const filterTool = metaTools.getTool("meta_filter_relevant_tools");
const filterTool = metaTools.getTool("meta_search_tools");
const searchResult = await filterTool.execute({
query: "employee time off vacation",
limit: 5,
Expand Down
8 changes: 4 additions & 4 deletions examples/meta-tools.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ const metaToolsWithOpenAI = async (): Promise<void> => {
{
role: 'system',
content: `You are an HR assistant with access to various HR tools.
Use the meta_filter_relevant_tools to find appropriate tools for user requests,
Use the meta_search_tools to find appropriate tools for user requests,
then use meta_execute_tool to execute them.`,
},
{
Expand Down Expand Up @@ -114,8 +114,8 @@ const directMetaToolUsage = async (): Promise<void> => {
const metaTools = await allTools.metaTools();

// Step 1: Search for relevant tools
const filterTool = metaTools.getTool('meta_filter_relevant_tools');
if (!filterTool) throw new Error('meta_filter_relevant_tools not found');
const filterTool = metaTools.getTool('meta_search_tools');
if (!filterTool) throw new Error('meta_search_tools not found');
const searchResult = await filterTool.execute({
query: 'employee management create update list',
limit: 5,
Expand Down Expand Up @@ -189,7 +189,7 @@ const dynamicToolRouter = async (): Promise<void> => {

// Create a router function that finds and executes tools based on intent
const routeAndExecute = async (intent: string, params: Record<string, unknown> = {}) => {
const filterTool = metaTools.getTool('meta_filter_relevant_tools');
const filterTool = metaTools.getTool('meta_search_tools');
const executeTool = metaTools.getTool('meta_execute_tool');
if (!filterTool || !executeTool) throw new Error('Meta tools not found');

Expand Down
26 changes: 13 additions & 13 deletions src/tests/meta-tools.spec.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ const createMockTools = (): BaseTool[] => {
return tools;
};

describe('Meta Tools', () => {
describe('Meta Search Tools', () => {
let tools: Tools;
let metaTools: Tools;

Expand All @@ -166,10 +166,10 @@ describe('Meta Tools', () => {
expect(metaTools.length).toBe(2);
});

it('should include meta_filter_relevant_tools', () => {
const filterTool = metaTools.getTool('meta_filter_relevant_tools');
it('should include meta_search_tools', () => {
const filterTool = metaTools.getTool('meta_search_tools');
expect(filterTool).toBeDefined();
expect(filterTool?.name).toBe('meta_filter_relevant_tools');
expect(filterTool?.name).toBe('meta_search_tools');
});

it('should include meta_execute_tool', () => {
Expand All @@ -179,12 +179,12 @@ describe('Meta Tools', () => {
});
});

describe('meta_filter_relevant_tools', () => {
describe('meta_search_tools', () => {
let filterTool: BaseTool;

beforeEach(() => {
const tool = metaTools.getTool('meta_filter_relevant_tools');
if (!tool) throw new Error('meta_filter_relevant_tools not found');
const tool = metaTools.getTool('meta_search_tools');
if (!tool) throw new Error('meta_search_tools not found');
filterTool = tool;
});

Expand Down Expand Up @@ -355,9 +355,9 @@ describe('Meta Tools', () => {

describe('Integration: meta tools workflow', () => {
it('should discover and execute tools in sequence', async () => {
const filterTool = metaTools.getTool('meta_filter_relevant_tools');
const filterTool = metaTools.getTool('meta_search_tools');
const executeTool = metaTools.getTool('meta_execute_tool');
if (!filterTool || !executeTool) throw new Error('Meta tools not found');
if (!filterTool || !executeTool) throw new Error('Meta search tools not found');

// Step 1: Discover relevant tools
const searchResult = await filterTool.execute({
Expand Down Expand Up @@ -394,7 +394,7 @@ describe('Meta Tools', () => {

expect(openAITools).toHaveLength(2);

const filterTool = openAITools.find((t) => t.function.name === 'meta_filter_relevant_tools');
const filterTool = openAITools.find((t) => t.function.name === 'meta_search_tools');
expect(filterTool).toBeDefined();
expect(filterTool?.function.parameters?.properties).toHaveProperty('query');
expect(filterTool?.function.parameters?.properties).toHaveProperty('limit');
Expand All @@ -411,17 +411,17 @@ describe('Meta Tools', () => {
it('should convert meta tools to AI SDK format', () => {
const aiSdkTools = metaTools.toAISDK();

expect(aiSdkTools).toHaveProperty('meta_filter_relevant_tools');
expect(aiSdkTools).toHaveProperty('meta_search_tools');
expect(aiSdkTools).toHaveProperty('meta_execute_tool');

expect(typeof aiSdkTools.meta_filter_relevant_tools.execute).toBe('function');
expect(typeof aiSdkTools.meta_search_tools.execute).toBe('function');
expect(typeof aiSdkTools.meta_execute_tool.execute).toBe('function');
});

it('should execute through AI SDK format', async () => {
const aiSdkTools = metaTools.toAISDK();

const result = await aiSdkTools.meta_filter_relevant_tools.execute?.(
const result = await aiSdkTools.meta_search_tools.execute?.(
{ query: 'ATS candidates', limit: 2 },
{ toolCallId: 'test-call-1', messages: [] }
);
Expand Down
10 changes: 5 additions & 5 deletions src/tool.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,7 @@ export class Tools implements Iterable<BaseTool> {
*/
async metaTools(): Promise<Tools> {
const oramaDb = await initializeOramaDb(this.tools);
const baseTools = [metaFilterRelevantTools(oramaDb, this.tools), metaExecuteTool(this)];
const baseTools = [metaSearchRelevantTools(oramaDb, this.tools), metaExecuteTool(this)];
const tools = new Tools(baseTools);
return tools;
}
Expand Down Expand Up @@ -323,7 +323,7 @@ export class Tools implements Iterable<BaseTool> {
}

/**
* Result from meta_filter_relevant_tools
* Result from meta_search_tools
*/
export interface MetaToolSearchResult {
name: string;
Expand Down Expand Up @@ -378,8 +378,8 @@ async function initializeOramaDb(tools: BaseTool[]): Promise<OramaDb> {
return oramaDb;
}

export function metaFilterRelevantTools(oramaDb: OramaDb, allTools: BaseTool[]): BaseTool {
const name = 'meta_filter_relevant_tools' as const;
export function metaSearchRelevantTools(oramaDb: OramaDb, allTools: BaseTool[]): BaseTool {
const name = 'meta_search_tools' as const;
const description =
'Searches for relevant tools based on a natural language query. This tool should be called first to discover available tools before executing them.' as const;
const parameters = {
Expand Down Expand Up @@ -472,7 +472,7 @@ export function metaFilterRelevantTools(oramaDb: OramaDb, allTools: BaseTool[]):
export function metaExecuteTool(tools: Tools): BaseTool {
const name = 'meta_execute_tool' as const;
const description =
'Executes a specific tool by name with the provided parameters. Use this after discovering tools with meta_filter_relevant_tools.' as const;
'Executes a specific tool by name with the provided parameters. Use this after discovering tools with meta_search_tools.' as const;
const parameters = {
type: 'object',
properties: {
Expand Down