docs: fix misleading MCP tool examples (get_configs, branch_id)

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
 

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

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