kirha logo

Tools

List available tools

Use kirha.tools() to list the catalogue. Pass focus to keep only the tools of one vertical, provider to keep only those of one provider:

import { Kirha } from "kirha";

const kirha = new Kirha({ apiKey: process.env.KIRHA_API_KEY });

const tools = await kirha.tools({ focus: "crypto" }); 
for (const tool of tools) { 
  console.log(`${tool.name}: ${tool.description}`); 
} 
from kirha import Kirha

kirha = Kirha()

tools = kirha.tools(focus="crypto")  
for tool in tools:  
    print(f"{tool.name}: {tool.description}")  

Vertical-scoped

Each vertical is a domain-specific collection of tools and providers. The tools returned depend on the vertical you pass. Browse them on the Providers Graph, or through the Catalogue if you are an agent 🤖

Each tool returned by kirha.tools() names its provider, what one call costs in creditsPerCall, and includes an inputSchema and outputSchema that describe the expected parameters and response shape. Always follow these schemas strictly when calling a tool, as malformed inputs will be rejected.

Browsing the catalogue is free. Only kirha.executeTool() consumes credits, and you can track usage on the Dashboard.

Each tool returned by kirha.tools() names its provider, what one call costs in credits_per_call, and includes an input_schema and output_schema that describe the expected parameters and response shape. Always follow these schemas strictly when calling a tool, as malformed inputs will be rejected.

Browsing the catalogue is free. Only kirha.execute_tool() consumes credits, and you can track usage on the Dashboard.

Page through the catalogue

kirha.tools() hands you the tools alone. Use kirha.listTools() when you also need to know how large the catalogue is:

const page = await kirha.listTools({ provider: "coingecko", page: 1, limit: 20 }); 
console.log(`${page.tools.length} of ${page.total} tools`); 

kirha.tools() hands you the tools alone. Use kirha.tools_page() when you also need to know how large the catalogue is:

page = kirha.tools_page(provider="coingecko", page=1, limit=20)  
print(f"{len(page.tools)} of {page.total} tools")  

The page carries tools, total across every page, the limit it was served with, and how many tools it skipped. Omit page and limit to get the whole list in one answer.

Find a tool for an intent

Use kirha.matchTools(query) to rank the tools that can carry out an intent written in plain language, most relevant first. You don't need to know the catalogue to use it:

const match = await kirha.matchTools("what is the price of a coin", { limit: 5 }); 
for (const tool of match.tools) { 
  console.log(`${tool.name} (${tool.creditsPerCall} credits): ${tool.description}`); 
} 

A tool carrying related: true was not matched against your query: it was pulled in because it chains with one of the tools that were, and relatedTo names those. Those tools come on top of limit, which caps the direct picks only, so a result can hold more tools than you asked for.

Use kirha.match(query) to rank the tools that can carry out an intent written in plain language, most relevant first. You don't need to know the catalogue to use it:

match = kirha.match("what is the price of a coin", limit=5)  
for tool in match.tools:  
    print(f"{tool.name} ({tool.credits_per_call} credits): {tool.description}")  

A tool carrying related=True was not matched against your query: it was pulled in because it chains with one of the tools that were, and related_to names those. Those tools come on top of limit, which caps the direct picks only, so a result can hold more tools than you asked for.

Read one tool

Use kirha.getTool(toolName) to read a single tool, with the other tools its provider serves:

const tool = await kirha.getTool("coingecko_searchCoin"); 
console.log(tool.inputSchema, tool.relatedTools); 

Use kirha.get(tool_name) to read a single tool, with the other tools its provider serves:

tool = kirha.get("coingecko_searchCoin")  
print(tool.input_schema, tool.related_tools)  

Execute a tool directly

Use kirha.executeTool(toolName, params) to call a specific tool with explicit parameters, bypassing the planning engine:

import { Kirha } from "kirha";

const kirha = new Kirha({ apiKey: process.env.KIRHA_API_KEY });

const result = await kirha.executeTool("coingecko_searchCoin", { 
  query: "avax", 
  limit: 1, 
}); 
console.log(result.output); 

Use kirha.execute_tool(tool_name, input) to call a specific tool with explicit parameters, bypassing the planning engine:

from kirha import Kirha

kirha = Kirha()

result = kirha.execute_tool("coingecko_searchCoin", {  
    "query": "avax",  
    "limit": 1,  
})  
print(result.output)  

When to use direct tool execution

Use kirha.search() or kirha.plan() when you have a natural language query and want KIRHA to pick the tools. This is the recommended approach for most use cases.

Execute a tool directly when you:

  • Already know which tool and parameters you need
  • Want to skip the planning step for your own orchestration logic
  • Need to call a single provider in isolation

Tools options

Taken by kirha.tools() and kirha.listTools():

Prop

Type

Taken by kirha.tools() and kirha.tools_page():

Prop

Type

Match options

Taken by kirha.matchTools(query, options):

Prop

Type

Taken by kirha.match(query), as keyword arguments:

Prop

Type

Execute tool options

Prop

Type

Prop

Type

On this page