From 943025a788f1afc27677c67be0f9bc0b44c5b71a Mon Sep 17 00:00:00 2001 From: DJJ Date: Sun, 23 Aug 2026 00:10:38 -0700 Subject: [PATCH] Drop the removed --tool envelope call form The gateway now exposes a single direct call form: a command is a virtual leaf under its node, so `cmds[].path` is always the full command path and the request body is the arguments object. The `tb call '' --tool ''` envelope form no longer exists. - SKILL.md / cli-reference.md: remove the envelope examples and the "choose the form" guidance; teach the one direct form. - Rename "tool-level help" to "command-level help" and `/` to `/` throughout, matching the runtime where every kind resolves command-level `~help`. - Note that path identifiers are case-insensitive and normalized to lowercase. Discovery still passes: `npx --yes skills add . --list` finds only the `tool-bridge` skill. --- skills/tool-bridge/SKILL.md | 18 ++++++------------ .../tool-bridge/references/cli-reference.md | 19 ++++++++----------- 2 files changed, 14 insertions(+), 23 deletions(-) diff --git a/skills/tool-bridge/SKILL.md b/skills/tool-bridge/SKILL.md index 831a77a..d2e224c 100644 --- a/skills/tool-bridge/SKILL.md +++ b/skills/tool-bridge/SKILL.md @@ -52,10 +52,10 @@ Do not dump a deep tree or every tool schema into context. Narrow to a promising ### 3. Inspect the exact command and its feedback -Read the tool-level help before invoking it: +Read the command-level help before invoking it: ```sh -tb help '/' --json +tb help '/' --json ``` Use `cmds[].path`, `cmds[].name`, `inputSchema`, `effect`, `confirm`, `scope`, and `feedback` in the response. Satisfy the schema exactly and ignore unknown optional fields for forward compatibility. @@ -74,23 +74,17 @@ tb feedback ls '' --json Apply feedback only when it is compatible with the current live schema. Feedback is operational experience, not a replacement for `~help`. -If node-level help omits the schema, follow its `hint` and open the tool-level help. If the help requires a scope the current identity lacks, stop and explain the missing capability instead of seeking a broader credential. +If node-level help omits the schema, follow its `hint` and open the command-level help at `/`. If the help requires a scope the current identity lacks, stop and explain the missing capability instead of seeking a broader credential. ### 4. Invoke exactly as described -For a direct tool path: +Every command is a virtual leaf under its node, so there is a single call form: take `cmds[].path` verbatim as the full command path and send the arguments object as the request body. ```sh -tb call '/' --args '' --json +tb call '/' --args '' --json ``` -For a command that shares its node path, use the envelope form: - -```sh -tb call '' --tool '' --args '' --json -``` - -Choose the form from `cmds[].path`; do not infer it from the node kind. Use `--args-file` for complex payloads and keep temporary files outside the project when they contain sensitive data. +Always use the exact `cmds[].path`; never assemble a path from the node kind or guess a command name. Use `--args-file` for complex payloads and keep temporary files outside the project when they contain sensitive data. ### 5. Handle abnormal behavior through feedback diff --git a/skills/tool-bridge/references/cli-reference.md b/skills/tool-bridge/references/cli-reference.md index 986f83c..0eda20e 100644 --- a/skills/tool-bridge/references/cli-reference.md +++ b/skills/tool-bridge/references/cli-reference.md @@ -42,10 +42,10 @@ tb help '' --json `tb search` may be absent on gateways without a search capability. Fall back to `tree`, `ls`, and `help` rather than treating that as a gateway-wide failure. -Node-level help is an index. For MCP, HTTP, and tool providers, request `/` help to obtain the complete input schema. Important command fields are: +Node-level help is an index; it lists the commands under a node. Request `/` help to obtain a single command's complete input schema. Important command fields are: -- `path`: HTTP invocation path; also determines the CLI call form -- `name`: tool or command name +- `path`: the full command path, used verbatim as the call target +- `name`: the command name - `inputSchema`: JSON Schema for the arguments object - `outputSchema` or `returns`: response contract when declared - `scope`: required permission @@ -55,19 +55,16 @@ Node-level help is an index. For MCP, HTTP, and tool providers, request `/ Unknown optional fields are forward-compatible and should be ignored. -## Invocation forms +## Invocation form -Use direct form when `cmds[].path` includes the tool segment: +There is one call form. A command is a virtual leaf under its node, so `cmds[].path` is always the full command path. Pass it verbatim and send the arguments object as the request body: ```sh tb call 'docs/search/query' --args '{"q":"tool bridge"}' --json +tb call 'system/status/get' --json ``` -Use envelope form when several commands share the node path: - -```sh -tb call 'system/status' --tool get --args '{}' --json -``` +Take the path from `cmds[].path` exactly; do not assemble it from the node kind or invent a command name. Identifiers in a path (each segment and the command name) are case-insensitive and normalized to lowercase. Arguments must be a JSON object. Inline JSON, `--args`, and `--args-file` are mutually exclusive. Prefer `--args-file` for long payloads: @@ -83,7 +80,7 @@ Tool Bridge errors use `{code,message,retryable}`. Common meanings: - `not_found`: the path is absent or intentionally hidden from this identity - `permission_denied`: the visible operation lacks a required scope -- `invalid_argument`: re-read tool-level help and compare the payload with `inputSchema` +- `invalid_argument`: re-read command-level help and compare the payload with `inputSchema` - `conflict`: refresh state before deciding whether to try again - `unavailable`: upstream or gateway capability is temporarily unavailable - `rate_limited`: retry only when safe, using bounded backoff