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