Using Tools

List, inspect, and call tools on connected MCP servers from the CLI.

List Tools

See all tools available on a connected server:

1belt mcp tools linear2belt mcp tools linear --json   # array of {name, description, inputSchema}34# Same output — `mcp run` with a bare slug lists tools instead of erroring5belt mcp run linear

1linear — 24 tools23tool                  description4list_issues           List issues with filtering and pagination5create_issue          Create a new issue6update_issue          Update an existing issue7get_issue             Get issue details by ID8list_projects         List all projects in the workspace9...

Inspect a Tool

View a tool's input schema before calling it:

1belt mcp tools linear:list_issues2belt mcp tools linear:list_issues --json   # single tool object with inputSchema34# Same schema view from the run command — handy when you already have slug:tool5belt mcp run linear:list_issues --help

1linear:list_issues23List issues with filtering and pagination45  required: project6  input schema:7  {8    "type": "object",9    "properties": {10      "project": {11        "type": "string",12        "description": "Project key to filter by"13      },14      "status": {15        "type": "string",16        "description": "Filter by status (backlog, todo, in_progress, done)"17      },18      "limit": {19        "type": "integer",20        "description": "Max results to return"21      }22    }23  }2425  run: belt mcp run linear:list_issues --input '{"project": "..."}'

Required fields and the sample --input line are derived from the tool's JSON Schema (required plus property types).

Call a Tool

Run a tool and get the result:

1# Inline JSON input (--input flag)2belt mcp run linear:list_issues --input '{"project": "INF", "limit": 5}'34# Positional JSON (same priority as --input when flag is omitted)5belt mcp run linear:list_issues '{"project": "INF", "limit": 5}'67# Input from file (@filename or path)8belt mcp run linear:create_issue --input @issue.json910# Piped stdin11echo '{"project": "INF"}' | belt mcp run linear:list_issues1213# No input required14belt mcp run slack:list_channels1516# Filter output with built-in jq (no external jq binary)17belt mcp run linear:list_issues --jq '.issues[] | .id'18belt mcp run linear:list_issues --jq '.issues[] | {id, title}'

Input resolves from --input, a positional argument, or piped stdin (in that order). See CLI setup — JSON input.

Use --jq to print only the fields you need. String values are unquoted (like jq -r); other values are compact JSON.

Pass tool arguments with -i / --input, a positional JSON argument, or piped stdin — not --args. An unknown flag prints the parse error on stderr and reminds you where input goes.

When the MCP server marks a result with is_error: true, the full JSON still prints to stdout (so you can inspect or re-filter it), but stderr includes the server's error text when the payload carries one (output, content[].text, message, or error). A line points at belt mcp tools <slug>:<tool> for the input schema. The process exits 1. With --jq, a filter written for the success shape may print nothing on stdout even though stderr has the failure detail — check $? and stderr, or drop --jq to see the raw payload.

MCP Apps pages in the web playground

In the workspace UI, open a connector from Explore → MCP servers (or /mcps/{slug}). When you run a tool whose result includes ui.html, the playground renders that MCP App page above the JSON output. The page runs in a sandboxed iframe with the CSP from the tool result; follow-up tool calls from the page are proxied to the same server.

Permalinks (/mcp-runs/{id}) reload the recorded run so you can inspect or tweak inputs and re-run. Tools that return input_required (MRTR) cannot complete nested calls from the embedded page — use the CLI or API retry flow instead.

Results are printed as formatted JSON (or filtered lines when --jq is set).

When the tool returns a partial page (for example next_cursor, has_more, or GraphQL-style pageInfo.hasNextPage), the CLI prints a muted hint on stderr after stdout:

• more results available: pass cursor <token> in --input to fetch the next page when the payload names a cursor
• more results available: this is one page. pass the server's cursor/page argument in --input to fetch the next when the payload only signals more pages without a cursor field

Pass the cursor in your next call's JSON input (field name depends on the MCP tool schema — often cursor, page, or after). Hints follow the same suppression rules as other stderr tips (INFSH_NO_TIPS=1, non-TTY stderr, and --jq on belt mcp run). See CLI setup — JSON output.

1{2  "issues": [3    {4      "id": "INF-123",5      "title": "Fix auth middleware",6      "status": "in_progress",7      "assignee": "okaris"8    }9  ]10}

Interactive elicitation (MRTR)

Some MCP tools cannot finish in a single round trip. The server returns an interim result with input_required: true and one or more input_requests (Multi Round-Trip Request / MRTR). Each request uses method elicitation/create with either:

belt mcp run handles this automatically in interactive terminals: it collects your answers or browser confirmation, retries the tool call with inputResponses and requestState, and repeats if the server asks for more input.

Non-interactive shells (CI set, no TTY, or BELT_NON_INTERACTIVE=1) cannot prompt. The CLI prints the MRTR envelope as JSON on stdout and exits with code 2:

1{2  "input_required": true,3  "input_requests": { "...": { "method": "elicitation/create", "params": { ... } } },4  "request_state": "..."5}

Parse input_requests, complete each elicitation step out of band (open URLs, collect form values), then retry via POST /mcps/{slug}/tools/{tool} with the original arguments, inputResponses, and requestState. See Credentials API — MCP tool proxy.

When the tool runs inside an agent chat, the runtime surfaces the same envelope on the tool invocation (awaiting_input + MCPInputState in data). Custom chat UIs should use submitMCPInput and the parsing helpers in @inferencesh/sdk ≥ v0.12.0 — see JavaScript SDK — MCP input requests.

Tool Reference Format

Tools are referenced as slug:tool_name:

1belt mcp tools <slug>              # list all tools2belt mcp run <slug>                # same as mcp tools <slug>3belt mcp tools <slug>:<tool>       # inspect one tool4belt mcp run <slug>:<tool> --help  # same schema view as tools <slug>:<tool>5belt mcp run <slug>:<tool>         # call a tool

Next

• Agent Tools — give your agents access to connector tools
• MCP Server — access these tools from Claude Code or Cursor