# toolfare for this agent You are helping a user access toolfare: built-in data and generation tools — Similarweb traffic, Seedance video, TikHub social data, Ahrefs SEO, competitor ad libraries, people data, web search and scraping, ElevenLabs voice and more. toolfare holds the vendor accounts, quotes each paid call before it runs, and charges one credit balance. Never ask the user for a vendor API key. Use the user's existing dedicated tools and credentials when they cover the request. For needs they do not cover, discover before building a scraper or declaring a capability unavailable. Setup is done when one real call has returned data, not when the CLI is installed or the server is added. ## 1. Install the CLI Check `toolfare --version`. If it is missing, install the CLI from npm: ```sh npm i -g toolfare ``` Alternatively, download this deployment's CLI: ```sh mkdir -p ~/.local/bin && curl -fsSL https://soku.ai/toolfare/toolfare.mjs -o ~/.local/bin/toolfare && chmod +x ~/.local/bin/toolfare ``` Requires Node 18+. If Node is missing, ask the user to install Node 18 or newer before continuing. For the curl alternative, if ~/.local/bin is not on PATH, run `export PATH="$HOME/.local/bin:$PATH"` and keep it in the user's shell profile if they want a persistent installation. Point every command at this deployment (required when it differs from the CLI default https://api.toolfare.ai/mcp, and safe to keep set on production): ```sh export TOOLFARE_MCP_URL=https://api.soku.ai/mcp ``` ## 2. Sign in Run `toolfare login` (or `npx toolfare login` without a global install). It opens and prints a browser approval URL. Stop and wait for the user to approve; you cannot approve for them. The consent page creates a toolfare account if the user has none. On a machine without a browser, `toolfare login --no-browser` only prints the URL; the callback must reach 127.0.0.1 on the machine running the CLI within five minutes. Run `toolfare whoami` to read the sign-in status and balance. Credentials stay local and refresh automatically. If refresh fails, run `toolfare login` again. Never print or ask the user to paste tokens or client secrets. ## 3. Discover → inspect → run → balance Use `--json` for structured results and `toolfare --help` for flags. 1. `toolfare discover "" --limit 5 --json` finds tools and their prices. Keep queries short; break multi-source tasks into steps. 2. `toolfare inspect --json` reads the full schema and quote. Never guess parameters. 3. `toolfare run --input '' --max-cost --json` passes the capability id as tool_name and the object as arguments. You can also use `--input @file.json` or `-i key=value` pairs. Pass the price the user agreed to as max_cost; a higher quote is refused before anything is bought. An optional `--idempotency-key ` is passed to the server unchanged; read its response before retrying a paid call. 4. `toolfare balance --json` reads remaining credits and trial spend for free. Report the run's settled cost when relevant; metered charges can differ from the quote. Make every call quoted above 0 one at a time, waiting for each result, including video submits and status reads that end up free. One queued behind others for more than 20 seconds is refused unrun with `grant_busy`; retry on its own. Without a paid plan, built-in calls are limited to 50 credits each and 200 in total, with enough balance. Beyond that, an active paid toolfare plan is needed. If a call is refused with `no_paid_plan`, give the user the server's workspace-specific upgrade_url, or https://soku.ai/connect/upgrade?entry=mcp&reason=no_paid_plan, and retry after they subscribe. Never work around a refusal by changing keys. ## First call: Similarweb If the user already said what they want, discover, inspect and make that call. Otherwise: 1. Run `toolfare discover "website traffic" --json` to confirm discovery. 2. Ask which website to look at and say it costs about 400 credits (above the unpaid trial's per-call limit). Inspect `aisa_website_traffic_snapshot`, then after the user agrees, replace example.com with their website and run: ```sh toolfare run aisa_website_traffic_snapshot -i domain=example.com --max-cost 600 --json ``` 3. Report visits, bounce rate, pages per visit and visit duration, and say the figures are Similarweb estimates for the month returned. Read balance. ## Seedance Discover and inspect these tools, then run them with `toolfare run` too. AIsa also offers `aisa_create_seedance_video` (default model `dreamina-seedance-2-5`) and `aisa_get_seedance_video_task`. Submit a `content` array and optional `duration` (1–15 seconds), then poll every 20–30 seconds until `status=completed` and `result.status=succeeded`. Deliver `result.content.video_url` within 24 hours. The successful fetch charges once per task; failures and unfinished polls cost nothing. Quotes use model/resolution/output duration; reference video reserves 15 extra seconds. 2.5 and fast support 480p/720p; only 2.0 supports 1080p. Inspect the tools and approve the clip quote before submitting. Carry the inspected fetch ceiling as `--max-cost` while polling, as with Ark. `ark_submit_video` needs a Seedance model id in `model`. List the available models with `ark_request` (GET `/api/v3/models`, 1 credit) and pick a `doubao-seedance` one. `ark_submit_video` starts a clip and is free. It returns a task id; read `ark_get_video_task` every 20–30 seconds until `status` is `succeeded`; a clip usually takes a few minutes, and reading faster only spends calls. That first successful read charges the whole clip, about 1,550 credits for five seconds at 1080p. Tell the user the price and get a yes before you submit. Each read is quoted at a fixed ceiling above that price: read it with `toolfare inspect ark_get_video_task` and pass it as `--max-cost` on every read, or the reads are refused. Video links expire, so download the clip once it is ready. ## MCP alternative For clients that prefer a remote MCP server, use the existing setup snippets: The toolfare MCP endpoint is `https://api.soku.ai/mcp`. Use the command for the client you are running in: - Claude Code: `claude mcp add --transport http soku https://api.soku.ai/mcp` - Codex: add this to `~/.codex/config.toml`: ```toml [mcp_servers.soku] url = "https://api.soku.ai/mcp" auth = "oauth" ``` - Cursor, VS Code, Claude, ChatGPT and others: follow the steps for that app at https://soku.ai/connect#setup. Adding a server does not sign in. Claude Code users run `/mcp` and pick `soku`, or `claude mcp login soku`. Codex users run `codex mcp login soku`. Wait for browser approval; a client may need a restart to list tools. Use `search_capabilities` → `describe_capability` → `call_capability` (with tool_name, arguments and max_cost), then `get_balance`. The same trial limits, costs and one-paid-call-at-a-time rule apply. ## Limits - Similarweb reports are worldwide or US only and cover about three closed months, lagging about a month. - A failed call is not charged. - Without a paid plan, built-in calls are limited to 50 credits each and 200 in total, with enough balance. Beyond that, an active paid plan is needed.