Skip to main content
Glama

Superpowers

by tools.superpowers
OverviewDiscussionsAdmin

Run a tool

run_tool

Run one tool with JSON input. Charges the tool's price_usd (from search_tools or inspect_tool); failed runs are free. If the call should cost more than $0.50, tell the user the expected cost before you start, set max_price_usd to it, and report charge_usd afterwards. Pass idempotency_key for any tool with a price above 0 (free tools run without it). Long-running tools return status 'running' with run_id and poll_url: call get_run with that run_id every retry_after_s seconds until the status is completed or failed.

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.
inputYesJSON input matching the tool's input schema (see inspect_tool).
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).
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_keyNoStable 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. Changed1 schema field changed
    • addedInput schema / properties / max_age_s
      Added value: +{
+  "description": "Free 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.",
+  "maximum": 2592000,
+  "minimum": 0,
+  "type": "integer"
+}
  2. Changed1 schema field changed
    • addedInput schema / properties / tags
      Added value: +{
+  "additionalProperties": {
+    "type": "string"
+  },
+  "description": "Optional 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.",
+  "type": "object"
+}
  3. Changed1 schema field changed
    • addedInput schema / properties / use_own_key
      Added value: +{
+  "description": "Default 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.",
+  "type": "boolean"
+}
  4. Changed2 schema fields changed
    • addedInput schema / properties / job
      Added value: +{
+  "description": "Short 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.",
+  "type": "string"
+}
    • changedInput schema / properties / project_id / description
      Previous value: -"Optional label to group usage by project."New value: +"Optional label to group usage by project or job (same as job)."
  5. Changed5 schema fields changed
    • addedInput schema / properties / agent_id / description
      Added value: +"Optional label to group usage by agent."
    • addedInput schema / properties / input / description
      Added value: +"JSON input matching the tool's input schema (see inspect_tool)."
    • addedInput schema / properties / project_id / description
      Added value: +"Optional label to group usage by project."
    • addedInput schema / properties / tool / description
      Added value: +"Tool slug from search_tools, e.g. brasilapi.cnpj."
    • addedInput schema / properties / trace_id / description
      Added value: +"Optional id tying related runs together, such as a plan_id."
  6. Changed2 schema fields changed
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"Required stable key for one logical operation. Reuse on retry; new key for new work."New value: +"Stable 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."
    • changedInput schema / required
      Previous value: -[
-  "tool",
-  "input",
-  "idempotency_key"
-]New value: +[
+  "tool",
+  "input"
+]
  7. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Discloses behavior far beyond the annotations: cost is charged per run at the tool's price_usd, failed runs are free, results may be served from cache with cache.fetched_at, and long-running calls go async with a run_id/poll_url. That the tool is neither read-only nor idempotent by default is handled by naming the idempotency_key escape hatch, so there is no tension with idempotentHint=false.

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

Conciseness5/5

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

Five sentences, purpose first, then the cost model, then the expensive-call protocol, then idempotency, then the async polling loop. Each sentence carries a distinct operational rule and none restates the schema or title.

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

Completeness5/5

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

With 11 parameters, nested input objects, and no output schema, the description still covers what comes back (charge_usd, status 'running', run_id, poll_url, cache.fetched_at) and the exact next-step loop. Nothing an agent needs to call this correctly and handle the response is missing.

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 already 100%, so the baseline is 3, but the description adds real operational semantics for two params: max_price_usd as a pre-authorized ceiling tied to a user disclosure step, and idempotency_key as required only for priced tools. It does not touch job/tags/agent_id/trace_id/max_age_s, though the schema documents those well.

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

Purpose4/5

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

States a specific verb and resource ('Run one tool with JSON input') and the scope word 'one' implicitly carves it out from run_batch and run_recipe. It doesn't name those siblings explicitly, so an agent must infer the boundary rather than being told it.

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

Usage Guidelines5/5

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

Gives explicit conditional rules: when the price exceeds $0.50, tell the user, set max_price_usd, and report charge_usd afterward; pass idempotency_key for any priced tool but not for free ones. It also prescribes the exact follow-up loop ('call get_run with that run_id every retry_after_s seconds until completed or failed'), leaving nothing to inference.

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