genai-toolbox/docs/en/how-to/invoke_tool.md

title, type, weight, description

title	type	weight	description
Invoke Tools via CLI	docs	10	Learn how to invoke your tools directly from the command line using the `invoke` command.

The invoke command allows you to invoke tools defined in your configuration directly from the CLI. This is useful for:

• Ephemeral Invocation: Executing a tool without spinning up a full MCP server/client.
• Debugging: Isolating tool execution logic and testing with various parameter combinations.

{{< notice tip >}} Keep configurations minimal: The invoke command initializes all resources (sources, tools, etc.) defined in your configuration files during execution. To ensure fast response times, consider using a minimal configuration file containing only the tools you need for the specific invocation. {{< /notice >}}

Before you begin

1. Make sure you have the toolbox binary installed or built.
2. Make sure you have a valid tool configuration file (e.g., tools.yaml).

Basic Usage

The basic syntax for the command is:

toolbox [--tools-file <path> | --prebuilt <name>] invoke <tool-name> [params]

• <tool-name>: The name of the tool you want to call. This must match the name defined in your tools.yaml.
• [params]: (Optional) A JSON string representing the arguments for the tool.

Examples

1. Calling a Tool without Parameters

If your tool takes no parameters, simply provide the tool name:

toolbox  --tools-file tools.yaml invoke my-simple-tool

2. Calling a Tool with Parameters

For tools that require arguments, pass them as a JSON string. Ensure you escape quotes correctly for your shell.

Example: A tool that takes parameters

Assuming a tool named mytool taking a and b:

toolbox --tools-file tools.yaml invoke mytool '{"a": 10, "b": 20}' 

Example: A tool that queries a database

toolbox  --tools-file tools.yaml invoke db-query '{"sql": "SELECT * FROM users LIMIT 5"}'

3. Using Prebuilt Configurations

You can also use the --prebuilt flag to load prebuilt toolsets.

toolbox --prebuilt cloudsql-postgres invoke cloudsql-postgres-list-instances

Troubleshooting

• Tool not found: Ensure the <tool-name> matches exactly what is in your YAML file and that the file is correctly loaded via --tools-file.
• Invalid parameters: Double-check your JSON syntax. The error message will usually indicate if the JSON parsing failed or if the parameters didn't match the tool's schema.
• Auth errors: The invoke command currently does not support flows requiring client-side authorization (like OAuth flow initiation via the CLI). It works best for tools using service-side authentication (e.g., Application Default Credentials).