Invoke Tools via CLI

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.

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.

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).

Command Usage

The basic syntax for the command is:

toolbox <tool-source> invoke <tool-name> [params]
  • <tool-source>: Can be --tools-file, --tools-files, --tools-folder, and --prebuilt. See the CLI Reference for details.
  • <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).
Last modified February 12, 2026: chore(main): release 0.27.0 (#2363) (c5524d3)