--- name: toolfare description: Use toolfare's built-in data and generation tools (website traffic, SEO, ad libraries, social and people data, web search and scraping, video and voice) through its CLI or MCP server. Use when the user needs data or generation their own tools and credentials do not cover. --- # 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 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. ## 0. Save this skill So later sessions find toolfare without this link, save this file as a skill where your agent loads skills from: - Claude Code: `mkdir -p ~/.claude/skills/toolfare && curl -fsSL https://toolfare.ai/skill.md -o ~/.claude/skills/toolfare/SKILL.md` - Codex: the same command with `~/.codex/skills/toolfare/SKILL.md` - Other agents: their own skills or rules folder; if they have none, skip this step. Everything below works without it. ## 1. Install the CLI Check `toolfare --version`. If it is missing, download this deployment's CLI: ```sh mkdir -p ~/.local/bin && curl -fsSL https://toolfare.ai/toolfare/toolfare.mjs -o ~/.local/bin/toolfare && chmod +x ~/.local/bin/toolfare ``` Use this download, not npm or npx: the `toolfare` npm package has no CLI release yet. Requires Node 18+. If Node is missing, ask the user to install Node 18 or newer before continuing. 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. ## 2. Sign in If `TOOLFARE_API_KEY` is set in the environment (a CI runner or a server), skip this step: every command already uses that key. Otherwise run `toolfare login`. It opens and prints a browser approval URL. Stop and wait for the user to approve; you cannot approve for them. If the user has no toolfare account yet, the approval page creates one first. 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 signed-in account and balance. Credentials stay local and refresh automatically. If refresh fails, run the login command 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 the remaining balance, in credits, 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. The user tops up a toolfare balance in US dollars and pays as you go; no subscription is required. Quotes, max_cost and the balance count credits: 1,000 credits = $3 ($0.003 each). When you tell the user a price or a balance, say it in dollars. Built-in calls are quoted before they run and need enough balance to cover the quote. If a call is refused with `insufficient_credits`, give the user the server's buy_credits_url (or https://toolfare.ai/app/billing) and retry after they top up (any amount from $3). Never work around a refusal by changing keys. ## First call: Ahrefs If the user already said what they want, discover, inspect and make that call. Otherwise make this one; it costs about 23 credits ($0.07), well inside the free $1.00 a new account starts with: 1. Run `toolfare discover "website traffic" --json` to confirm discovery. 2. Ask which website to look at (their own, or a competitor's). Inspect `ahrefs_site_metrics`, then replace example.com with that website and `` with yesterday's date (YYYY-MM-DD) and run: ```sh toolfare run ahrefs_site_metrics -i target=example.com -i date= -i mode=subdomains --max-cost 40 --json ``` A `provider_error` is not charged: wait a minute and retry once. 3. Report estimated monthly organic traffic, organic keywords and keywords in the top 3, and say they are Ahrefs estimates. Read balance. 4. Offer a next step: Similarweb visits and traffic sources for the same site (`aisa_website_traffic_snapshot`, about 400 credits, $1.20), or which keywords it ranks for. ## Seedance Discover and inspect these tools, then run them with `toolfare run ` too. Video needs a first top-up of any amount: the free balance a new account starts with covers data calls only, and a video call before any top-up is refused with `purchase_required`. Give the user the buy_credits_url it carries. Seedance runs through `seedance_video`: `model` is `seedance-2.5`, `seedance-2.0`, `seedance-2.0-fast` or `seedance-2.0-mini`, with a `prompt` (or `first_frame` / reference media), `seconds` (4–15, default 5) and `resolution` (480p or 720p; 1080p only on seedance-2.0; default 720p). It is quoted before it runs: tell the user the price and get a yes, then pass that quote as `--max-cost`. Starting is free and returns a `task_id`. Read `get_result` with that `task_id` every 20–30 seconds until `status` is `succeeded`; a clip usually takes a few minutes, and reading faster only spends calls. The read that returns the clip charges it once, at the same quote, with `--max-cost` at or above it; unfinished reads and failed clips are free. Five seconds of seedance-2.5 is about 180 credits ($0.54) at 480p and 405 ($1.22) at 720p. Download `urls` once it is ready; links expire. Seedream images run through `seedream_image` (`model` such as `seedream-5.0-lite`, a `prompt`), and edits through `seedream_image_edit` (with `image`); they usually come back in the same call. Any tool that answers with a `task_id` instead of its result is read the same way: call `get_result` with that `task_id` until `status` is `succeeded`. ## MCP alternative For clients that prefer a remote MCP server, use the existing setup snippets: The toolfare MCP endpoint is `https://api.toolfare.ai/mcp`. Use the command for the client you are running in: - Claude Code: `claude mcp add --transport http toolfare https://api.toolfare.ai/mcp` - Codex: add this to `~/.codex/config.toml`: ```toml [mcp_servers.toolfare] url = "https://api.toolfare.ai/mcp" auth = "oauth" ``` - Cursor, VS Code, Claude, ChatGPT and others: follow the steps for that app at https://toolfare.ai/docs#connect. Adding a server does not sign in. Claude Code users run `/mcp` and pick `toolfare`, or `claude mcp login toolfare`. Codex users run `codex mcp login toolfare`. 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 billing policy, costs and one-paid-call-at-a-time rule apply. ## Limits - Similarweb reports are worldwide only and cover about three closed months, lagging about a month. - A failed call is not charged. - The user tops up a toolfare balance in US dollars and pays as you go; no subscription is required. Quotes, max_cost and the balance count credits: 1,000 credits = $3 ($0.003 each). When you tell the user a price or a balance, say it in dollars. Built-in calls are quoted before they run and need enough balance to cover the quote.