From 19965a7c3689d74408a128b4a55b88cc37b599f1 Mon Sep 17 00:00:00 2001 From: Petr Date: Sat, 28 Mar 2026 18:28:12 +0100 Subject: [PATCH] docs: fix misleading MCP tool examples and add schema discovery guidance Fix wrong get_config example (should be get_configs with configs list param), clarify that branch_id is a CLI flag not a tool input parameter, and add schema discovery tips to context, mcp-workflow, and gotchas docs. Fixes #68 --- .../skills/kbagent/references/gotchas.md | 5 ++++ .../skills/kbagent/references/mcp-workflow.md | 26 +++++++++++++++---- src/keboola_agent_cli/commands/context.py | 10 ++++++- 3 files changed, 35 insertions(+), 6 deletions(-) diff --git a/plugins/kbagent/skills/kbagent/references/gotchas.md b/plugins/kbagent/skills/kbagent/references/gotchas.md index e664635a..e317e8ed 100644 --- a/plugins/kbagent/skills/kbagent/references/gotchas.md +++ b/plugins/kbagent/skills/kbagent/references/gotchas.md @@ -58,7 +58,12 @@ One project failing does not block others. Check the `errors` array: - **Write tools** (multi_project=false): require `--project` to specify the target. - **Auto-expand**: tools like `list_tables` that need `bucket_id` auto-resolve it by calling `list_buckets` first. - **Input validation**: tool input is validated against the tool's `inputSchema` before dispatch. + Only pass parameters defined in the schema. Unexpected parameters cause Pydantic validation errors. - **Branch scope**: when active branch is set, MCP tools automatically scope to that branch. + `branch_id` is a **CLI flag** (`--branch`), NOT a tool input parameter -- do not pass it inside `--input`. +- **Schema discovery**: use `kbagent --json tool list` to inspect each tool's `inputSchema` and find + accepted parameters. For example, `get_configs` takes `configs` (a list of `{component_id, configuration_id}` + objects), not a flat `config_id` string. ## Config resolution order diff --git a/plugins/kbagent/skills/kbagent/references/mcp-workflow.md b/plugins/kbagent/skills/kbagent/references/mcp-workflow.md index e76431b5..aee590d9 100644 --- a/plugins/kbagent/skills/kbagent/references/mcp-workflow.md +++ b/plugins/kbagent/skills/kbagent/references/mcp-workflow.md @@ -28,11 +28,24 @@ kbagent --json tool call list_configs --project prod kbagent --json tool call create_config --project prod \ --input '{"component_id": "keboola.ex-db-snowflake", "name": "My Extract"}' -# Get config details with parameters -kbagent --json tool call get_config \ - --input '{"configuration_id": "12345"}' +# Get specific config details (note: configs takes a list of {component_id, configuration_id}) +kbagent --json tool call get_configs \ + --input '{"configs": [{"component_id": "keboola.snowflake-transformation", "configuration_id": "12345"}]}' ``` +## Discovering tool parameters + +Each MCP tool has an `inputSchema` that defines accepted parameters. To see +the schema for a specific tool, use `tool list` with `--json`: + +```bash +# List all tools with their input schemas +kbagent --json tool list | jq '.data.tools[] | select(.name == "get_configs") | .inputSchema' +``` + +**Important**: Only pass parameters defined in the tool's `inputSchema` via `--input`. +Unexpected parameters cause Pydantic validation errors on the MCP server side. + ## Input format Pass tool parameters as a JSON object via `--input`. Three formats are supported: @@ -54,16 +67,19 @@ Input is validated against the tool's `inputSchema` before execution. ## Branch support -Use `--branch ID` to scope tool calls to a development branch: +Use the CLI flag `--branch ID` to scope tool calls to a development branch: ```bash # List tools available on a branch kbagent --json tool list --project prod --branch 456 # Call a tool on a branch -kbagent --json tool call list_configs --project prod --branch 456 +kbagent --json tool call get_configs --project prod --branch 456 \ + --input '{"configs": [{"component_id": "keboola.snowflake-transformation", "configuration_id": "12345"}]}' ``` +- `--branch` is a **CLI flag**, not a tool input parameter. Do NOT pass `branch_id` + inside `--input` JSON -- it will be rejected as an unexpected keyword argument. - `--branch` requires `--project` (forces single-project mode) - If a branch is active via `kbagent branch use`, it is applied automatically -- no need to pass `--branch` manually diff --git a/src/keboola_agent_cli/commands/context.py b/src/keboola_agent_cli/commands/context.py index 2f71c418..814450a8 100644 --- a/src/keboola_agent_cli/commands/context.py +++ b/src/keboola_agent_cli/commands/context.py @@ -198,11 +198,12 @@ ### MCP Tools (Multi-Project) kbagent tool list [--project NAME] [--branch ID] - List MCP tools. multi_project=true: reads all projects. false: single project. + List MCP tools with inputSchema. Use --json to inspect accepted parameters. kbagent tool call TOOL_NAME [--project NAME] [--input JSON|@file|-] [--branch ID] Call an MCP tool. Read tools auto-query all projects. Write tools need --project. --input accepts: inline JSON, @file.json (from file), or - (from stdin). + --branch is a CLI flag (NOT a tool input param). Do not pass branch_id in --input. ### Utility Commands @@ -253,6 +254,13 @@ 8. Config resolution order: --config-dir flag > KBAGENT_CONFIG_DIR env > .kbagent/ in CWD/parents > ~/.config/keboola-agent-cli/ +9. MCP tool parameters -- discover with `kbagent --json tool list`: + - Only pass parameters defined in the tool's inputSchema via --input + - branch_id is a CLI flag (--branch), NOT a tool input parameter + - Example: get_configs uses "configs" (list of objects), not flat "config_id" + kbagent --json tool call get_configs --project prod --branch 456 \\ + --input '{{"configs": [{{"component_id": "keboola.snowflake-transformation", "configuration_id": "12345"}}]}}' + ## Exit Codes 0 Success