Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 6 additions & 12 deletions skills/tool-bridge/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 '<node>/<tool>' --json
tb help '<node>/<command>' --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.
Expand All @@ -74,23 +74,17 @@ tb feedback ls '<exact-tool-or-node-path>' --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 `<node>/<command>`. 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 '<node>/<tool>' --args '<json-object>' --json
tb call '<node>/<command>' --args '<json-object>' --json
```

For a command that shares its node path, use the envelope form:

```sh
tb call '<node>' --tool '<command>' --args '<json-object>' --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

Expand Down
19 changes: 8 additions & 11 deletions skills/tool-bridge/references/cli-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,10 @@ tb help '<path>' --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 `<node>/<tool>` 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 `<node>/<command>` 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
Expand All @@ -55,19 +55,16 @@ Node-level help is an index. For MCP, HTTP, and tool providers, request `<node>/

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:

Expand All @@ -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
Expand Down
Loading