Skip to main content
Glama

Superpowers

by tools.superpowers
OverviewDiscussionsAdmin

Run a tool on many inputs

run_batch

Run one tool over many inputs (up to 500) in one call, e.g. verify 300 emails or look up 100 companies. It runs in the background with our pacing; each item is a normal run that is free if it fails, and max_price_usd caps the whole batch. If price_usd times the number of inputs is above $0.50, tell the user that total before you start. Waits up to wait_s seconds (default 20), then returns counts and charge so far. Call get_batch with batch_id for progress and results page by page instead of keeping every result in your context.

Input Schema

NameRequiredDescriptionDefault
jobNoShort name of the recurring task this run belongs to, e.g. daily-competitor-ads. Use the same name every time the task runs: the person sees those runs together in their app, with the schedule they keep. Same as project_id.
tagsNoOptional key=value labels for this run, e.g. {"campaign": "launch"}. They are added to the tags of the API key you use (which you can't change here) and let your human split spend and set limits per tag.
toolYesTool slug from search_tools, e.g. brasilapi.cnpj.
inputsYesOne input object per item, each in the tool's input schema
wait_sNo
agent_idNoOptional label to group usage by agent.
trace_idNoOptional id tying related runs together, such as a plan_id.
max_age_sNoFree repeat lookups: if you already ran this tool with exactly this input and it succeeded at most this many seconds ago, get that result back free, with cache.fetched_at, instead of a new paid call. E.g. 86400 for a company record, 3600 for search results. Omit for a fresh call.
project_idNoOptional label to group usage by project or job (same as job).
concurrencyNo
use_own_keyNoDefault true: when your human connected their own key for this tool's vendor (superpowers.tools/app/connections), the call goes through their account and costs nothing here. Pass false to use Superpowers credit instead, e.g. when their key ran out.
max_price_usdNoHard total buyer charge ceiling, including all job/comparison steps.
idempotency_keyYesStable key for one logical operation (1-128 letters, digits, _ . : / -). Reuse it to retry the same request, so a retry returns the first result instead of charging twice; use a new key for new work. Required by compare_providers, run_job and run_tool on tools that can charge; free tools (price 0) run without it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior beyond the annotations: background execution with vendor pacing, per-item failure being free, max_price_usd as a whole-batch ceiling, the wait_s polling window and what is returned after it, and the anti-context-bloat advice to page results via get_batch. These are exactly the traits an agent needs before committing to a paid batch.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core capability and scope, then costs, then waiting, then follow-up. Four dense sentences with little waste, though the cost-disclosure rule could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter, nested-input, charging batch tool with no output schema, the description covers cost, wait semantics, failure economics, and result retrieval. It does not describe partial-failure reporting in the return payload, which is the main residual gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is high (85%) so the baseline is 3, but the description adds real semantics for otherwise thin parameters: wait_s gains a default and a described return behavior, and max_price_usd gains the 'caps the whole batch' meaning. The remaining 12 parameters are left to the (already thorough) schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Run one tool over many inputs (up to 500) in one call') and immediately distinguishes itself from the single-input sibling run_tool via the 'many inputs' scope. The examples (verify 300 emails, look up 100 companies) make the batch nature concrete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context and a concrete pre-flight rule ('If price_usd times the number of inputs is above $0.50, tell the user'), plus routes result retrieval to get_batch. It never explicitly states when not to use this versus run_tool/run_job/compare_providers, so the alternative-selection guidance is implied rather than complete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Superpowers toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources