# tooldance — Caller Guide (for AI agents) > The service lives at **** — docs, the CLI, and these guides > are all there. Grab the CLI: [`tooldance.sh`](https://tool.dance/tooldance.sh). You *call* tools over a **tooldance** service. Each tool takes a JSON argument object and returns a JSON result; you invoke it by name. This guide covers how to discover what's available and how to call it with the `tooldance.sh` CLI. ## Setup `tooldance.sh` is a thin wrapper over the HTTP API. It targets **https://tool.dance** by default, so the only thing you must set is your token: ```bash export TOOLDANCE_KEY=your-access-token # required — your access token # Optional: point at a different service (defaults to https://tool.dance) # export TOOLDANCE_HOST=https://your-tooldance.example.com ``` The CLI needs `curl`; **named-parameter** calls (the `--flag` form) additionally need `jq` on `PATH` (raw-JSON calls and discovery don't). Throughout this guide `tooldance` means the `tooldance.sh` script (run it as `./tooldance.sh` or put it on your `PATH` as `tooldance`). ## Step 1 — Discover what you can call Run with **no arguments** to print the readme: every tool available to you, each with its description. **Always do this first** — it's how you learn the tool names and what they expect. ```bash tooldance ``` ``` tooldance ========= Available tools: tooldance weather Current weather for a city. Args: { city: string (required) — city name, e.g. "Toronto" } Returns: { city, tempC: number, conditions: string } tooldance geocode Geocode a street address to coordinates. Args: { address: string (required); country?: string (ISO-3166, default "US") } Returns: { lat, lng, formatted } Usage: tooldance '' call with a raw JSON body tooldance --key value ... call with named params -> JSON ... ``` The listing shows **the tools available to you**. The description is the tool's entire documentation — read it for the exact argument shape, since tooldance has no separate schema. If a description is vague, send a minimal body and inspect the error. (Equivalent raw endpoint, if you prefer `curl`: `curl -fsS "$TOOLDANCE_HOST/readme?format=cli" -H "Authorization: Bearer $TOOLDANCE_KEY"`.) ## Step 2 — Call a tool There are three call forms. Pick whichever is convenient. ### A. Raw JSON body (most precise) Pass one argument that is a JSON object. Use this when args are nested, typed, or you already have JSON: ```bash tooldance weather '{"city": "Toronto"}' tooldance geocode '{"address": "1 Infinite Loop, Cupertino", "country": "US"}' ``` ### B. Named parameters (convenient, needs `jq`) The CLI assembles `--key value` pairs into a JSON object: ```bash tooldance weather --city Toronto tooldance geocode --address "1 Infinite Loop" --country US ``` Rules for named params: - `--key value` and `--key=value` are both accepted. - A bare `--flag` (no value, or followed by another `--flag`) becomes `true`: `tooldance report --verbose` → `{"verbose": true}`. - **Values that parse as JSON are sent typed**; everything else is a string: - `--times 3` → `{"times": 3}` (number) - `--enabled true` → `{"enabled": true}` (boolean) - `--tags '["a","b"]'` → `{"tags": ["a","b"]}` (array) - `--name Toronto` → `{"name": "Toronto"}` (string) - To force a numeric-looking value to stay a **string**, quote it as JSON: `--zip '"90210"'` → `{"zip": "90210"}`. ### C. No arguments → empty body If a tool takes no input, call it with just the name; the body defaults to `{}`: ```bash tooldance now ``` ## Step 3 — Read the result On success the CLI prints the JSON response. The result envelope is always: ```json { "ok": true, "result": } ``` The useful payload is under `result`. Pipe through `jq` to extract fields: ```bash tooldance weather --city Toronto | jq '.result.tempC' ``` ## Errors On failure you get a non-2xx HTTP status and `{ "ok": false, "error": "..." }`. Because the CLI calls `curl -fsS`, a failing call **exits non-zero** and may not print the body. To see the error message, hit the endpoint without `-f`: ```bash curl -sS -X POST "$TOOLDANCE_HOST/weather" \ -H "Authorization: Bearer $TOOLDANCE_KEY" \ -H "Content-Type: application/json" \ -d '{}' # -> 500 { "ok": false, "error": "city is required" } ``` Common statuses you'll see as a caller: | status | meaning | what to do | |--------|---------|------------| | 400 | malformed JSON body or too large (>1 MiB) | fix the body | | 401 | missing/invalid `TOOLDANCE_KEY` | check the token / env var | | 403 | that tool isn't available to you | call one that appears in `tooldance` | | 404 | no such tool | re-run `tooldance` to see current names | | 500 | the tool threw (often bad/missing args) | read the error, fix the args | | 503 | concurrency limit | retry with backoff (a few calls may be in flight) | | 504 | the tool exceeded its timeout | the operation was too slow; retry or narrow the input | If a tool returns `403` or never appears in `tooldance`, it simply isn't available to you — stick to the tools the listing shows. ## Tips for agents - **Discover before calling.** Run `tooldance` to get exact names and arg docs; don't guess names — typos return `404`. - **Prefer raw JSON (`'{...}'`) for anything non-trivial.** It avoids `jq`-dependency and shell-quoting surprises with nested or typed values. - **Mind value typing** in named-param mode: `--count 5` is a number, not the string `"5"`. Quote-as-JSON (`'"5"'`) when a tool wants a string. - **Treat the description as the contract.** There's no schema; the description is all the documentation that exists. - **Results and bodies are bounded** (call body ≤1 MiB, result ≤10 MiB). For large data, look for a tool that paginates or summarizes rather than dumping. - **Concurrency**: you may have a small number of calls in flight at once (default 4 per key); on `503`, back off and retry rather than hammering. ## Quick reference ```bash tooldance # list tools you can call (+ descriptions) tooldance # call with empty body {} tooldance '{"k": "v"}' # call with a raw JSON body tooldance --k v --flag # call with named params -> JSON (needs jq) tooldance ... | jq .result # extract the payload ```