Skip to main content
Glama

Superpowers

by tools.superpowers
OverviewDiscussionsAdmin

Compare providers

compare_providers

Run the same input across several providers of a category and get results side by side with cost and latency. Each provider charges its own price: 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. Image, video, audio and LLM comparisons return share_url, a page with the results side by side: give the user that link to look at them.

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.
inputYesJSON input matching the tool's input schema (see inspect_tool).
toolsNoTool slugs to include; omit to use every live provider in the category.
agent_idNoOptional label to group usage by agent.
categoryYesCategory slug from list_categories.
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_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. 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. Changed6 schema fields changed
    • addedInput schema / properties / agent_id / description
      Added value: +"Optional label to group usage by agent."
    • addedInput schema / properties / category / description
      Added value: +"Category slug from list_categories."
    • 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 / tools / description
      Added value: +"Tool slugs to include; omit to use every live provider in the category."
    • addedInput schema / properties / trace_id / description
      Added value: +"Optional id tying related runs together, such as a plan_id."
  6. Changed1 schema field 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."
  7. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false/openWorldHint=true/idempotentHint=false but say nothing about billing. The description adds real value beyond them: that each provider charges its own price, a $0.50 spend-approval threshold, the max_price_usd/charge_usd contract, and the share_url return for media categories. It omits what happens on partial failure across providers, which is the main remaining gap.

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?

Three sentences, front-loaded with the purpose before the cost procedure and the return-behavior note. Efficient, though the pricing clause is slightly dense and 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 12-parameter, nested-object, charging tool with no output schema, the description covers purpose, cost-control flow and the share_url return. It leaves the multi-provider partial-failure and idempotency interaction unstated, but nothing essential to invoking it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so all 12 parameters are already documented, and the description only adds usage for max_price_usd ('set max_price_usd to it') and references charge_usd. Baseline 3 applies when the schema does the heavy lifting.

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 and resource: run the same input across several providers of a category and return results side by side with cost and latency. This is clearly distinguishable from sibling run_tool (a single tool) and from the list/search tools, so an agent can pick it without opening the schema.

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 a concrete conditional workflow ('if the call should cost more than $0.50, tell the user... set max_price_usd... report charge_usd') and tells the agent to surface share_url to the user. It does not explicitly name the sibling alternative (run_tool) or say when-not to use this, so it stops short of full routing guidance.

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