Superpowers

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

Annotations already declare destructive, non-idempotent, non-open-world behavior; the description adds crucial context: human approval must happen first, the card must be named, every charge triggers an email, and specific failure modes route to topup_url. It does not explicitly warn about duplicate charges on retry despite the non-idempotent annotation, but overall it adds strong behavioral context.

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

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

The purpose is front-loaded, then approval preconditions, fallback routing, and email notification follow in compact form. Every sentence carries operational information with no redundant restatement.

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

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

For a destructive financial mutation with no output schema, the description covers the approval workflow, fallback alternatives, and notification behavior well. It could more explicitly address retry/duplicate-charge risk or post-charge verification, but the core operational picture is complete enough to invoke correctly.

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

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

Schema coverage is 100%, covering amount bounds and the human_approved flag. The description adds meaningful semantics beyond the schema: the amount and card must have been named in the approval conversation, get_balance shows the card, and human_approved should be true only after an explicit yes.

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

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

The description states a specific verb and resource: 'Add credit by charging your human's saved card.' It distinguishes the tool from the sibling create_topup by explicitly routing cases with no saved card, disabled agent charges, or bank confirmation to the topup_url flow.

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

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

It gives an explicit precondition: ask the human in this conversation, name the amount and card, get a yes, then set human_approved true. It also names three situations where the agent should not use this tool and should use create_topup instead.

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

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.

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.

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.

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.

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.

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.

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

Beyond the annotations (which only declare it is a non-idempotent write with no destructive/open-world hint), the description discloses the permission gate, tag inheritance, that the new key counts against the parent limit and cannot exceed it, and that the secret is returned only once with an explicit 'store it, never print it' warning. This is exactly the extra context annotations cannot carry.

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

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

Front-loads the core action, then layers purpose, prerequisite, inheritance rules, and the secret-handling warning. Every sentence carries information, though the density is high and slightly longer than strictly necessary.

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

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

For a mutating tool with no output schema, the description covers the essential return behavior (secret returned once), the authorization requirement, and the limit/tag inheritance constraints an agent must know to call it correctly. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters in detail. The description restates the same fields and constraints (tags inherit, limit cannot exceed parent's) without adding new syntax or semantics beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Create an API key') and enumerates the created fields (label, tags, monthly limit), letting an agent separate it from siblings like list_keys, revoke_key and update_key. The spend-splitting example clarifies what the tool is for without ambiguity.

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

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

Gives a clear usage scenario ('one key per sub-agent or per persona so spend splits and caps separately') and a hard prerequisite (requires the can_manage_keys permission). It stops short of naming alternative tools or stating when *not* to use it, so it is strong context rather than full when/when-not routing.

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

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

Beyond the annotations (which only say it's non-read-only, non-idempotent, non-destructive), the description discloses substantial behavior: the link opens without sign-in, is valid for 7 days, lets the human pick the amount, supports saved or new cards and auto top-up, and cannot be paid by the agent itself. This is exactly the context annotations cannot convey.

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

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

Front-loads the trigger, then layers mechanism, constraints, and the parameter note in compact sentences. Slightly dense but every clause (expiry, no sign-in, self-pay prohibition) carries useful information.

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

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

With no output schema, the description steps in to describe the returned topup_url and optional checkout_url, plus validity window and payer rules. Complete for an agent to invoke it correctly; only the sibling-alternative routing is left implicit.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: amount_usd is a *suggestion* (the human still chooses), and setting it also produces a checkout_url going straight to Stripe. That clarifies intent and side effect beyond the schema's 'Suggested amount' text.

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

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

States a specific outcome: it returns topup_url, a link to send to the user, and optionally a checkout_url. The purpose (generate a human-payable top-up link) is unambiguous, though it never explicitly contrasts itself with the sibling charge_saved_card, which an agent might otherwise consider.

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

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

Opens with an explicit trigger condition, 'When you run low on credit', and adds the routing constraint 'You cannot pay it yourself', which tells the agent to hand off to the human rather than paying directly. It stops short of naming charge_saved_card or get_balance as alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it discloses the exact data payload and notes that topup_url is a sign-in-free link for a human to open — a non-obvious interaction detail. It does not mention rate limits or error conditions, hence not a 5.

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

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

One compact sentence with the primary value (balance in USD) front-loaded and the secondary fields trailing. The mid-sentence list of returned fields is dense but each item carries information; nothing is padding.

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

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

There is no output schema, so the description must carry the return-value burden, and it does so completely by enumerating every returned field including the conditional saved card and the topup_url explanation. An agent has everything needed to call this correctly and interpret the result.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies; the description correctly focuses on outputs instead of inventing parameter detail.

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

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

The description enumerates exactly what the tool returns (balance in USD, saved card, chargeability, auto top-up, topup_url), which makes its purpose unambiguous and distinguishes it from siblings like get_usage or get_reviews. It lacks an explicit verb+resource framing ('Get balance' comes from the title), but the resource and scope are clear.

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

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

Usage is only implied: an agent can infer this is the pre-flight check before charge_saved_card or create_topup, but the description never states when to call it or what alternatives exist. For a zero-parameter read tool this is largely adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the possible progress states, that results are returned in input order, and that view controls normalized vs output results — details the annotations cannot convey.

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

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

Two dense sentences, front-loaded with the primary outcome (progress + results) before paging and REST details. Nothing is redundant, though the parenthetical field list is slightly cramped.

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

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

With no output schema, the description carries the return-value burden and does so by listing the result fields and their ordering. It also flags the REST alternative for bulk downloads. Minor gap: batch ID format and what a 'not_run' or partial batch looks like are left implicit.

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

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

Schema description coverage is 75%, so most parameters are self-documenting, and the description reinforces the offset/limit paging model and hints at the 'view' enum via 'normalized result (or output)'. The required batch_id has no description in either place, and no parameter receives additional format or constraint detail beyond the schema.

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

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

The description states a specific verb and resource — retrieving a batch's progress plus a page of its results — and enumerates the returned fields (index, input, status, result, error). It is easy to tell apart from run_batch and get_run from the text alone, though no sibling is named explicitly.

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

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

Pagination guidance ('Page with offset/limit') and the alternative REST download route for full result sets give implied usage context. However, there is no explicit statement of when to use this versus sibling tools such as get_run or run_batch, so the guidance remains inferred.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the description is not required to restate safety. It does add genuinely new context: the contents returned (SKILL.md, cost, script_url) and the trust caveat that community recipes come from other users, with an instruction to disclose behavior to the user before following it. It stops short of noting failure modes or whether fetching has side effects.

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

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

Two sentences, both front-loaded and free of filler. The return contents come first, followed by the community-recipe caveat, so the most decision-relevant information leads.

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

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

With no output schema, the description usefully enumerates the return shape, and it flags the community-recipe trust issue. It is nearly complete for a simple single-param read tool, though it could be clearer about the read-then-run workflow relative to run_recipe.

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

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

Schema coverage is 100% and the schema already documents the single 'recipe' parameter as a slug from list_recipes. The description adds no syntax, format, or sourcing detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Read) and resource (a recipe) and enumerates exactly what it returns: SKILL.md steps, inputs, typical cost, and script_url. An agent can distinguish this from list_recipes (enumeration) and run_recipe (execution) without opening a schema.

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

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

The description implies usage by describing the SKILL.md as 'the steps to follow with Superpowers tools', suggesting this is the read-before-run step, and adds a caution for community recipes. However, it never explicitly states when to use this versus run_recipe or list_recipes, leaving the routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine domain context about the reward model ($5 starting bonus, credit on activation), but says nothing about the shape of the returned data or what 'stats' contains.

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

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

Two short sentences, the primary resource stated first, with the reward mechanic as supporting detail. No filler, no redundancy.

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

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

For a zero-parameter read tool with no output schema, the description is close to sufficient, and the annotations cover the safety semantics. The one gap is that 'stats' is left undefined, so the agent doesn't know what fields to expect in the response.

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

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

The tool takes zero parameters, so there is nothing for the description to document. The baseline of 4 applies; the sentence about the referral program is tangential to parameter meaning.

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

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

The noun phrase 'The user's invite link and stats' names a specific resource, so an agent can tell this apart from siblings like get_balance, get_usage, or get_share. It's clear but relies on an implied verb ('get') rather than stating the operation outright.

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

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

The description gives no when-to-use guidance, no prerequisites, and never names or contrasts with an alternative such as get_share or get_reviews. The agent must infer that this is the tool for referral-program information purely from the name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that the result is a public rating plus recent reviews, but says nothing about how many reviews, pagination, or sorting.

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

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

A single sentence with no filler, front-loading the core action and the data returned. Nothing can be trimmed without losing meaning.

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

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

For a one-parameter read tool with full schema coverage, rich annotations, and no output schema, the description is nearly sufficient as-is. Only minor gaps remain around result size and ordering of the returned reviews.

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

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

With a single parameter at 100% schema description coverage, the schema already documents the slug format and gives an example. The description's phrase 'a tool' refers to the same parameter without adding any new semantics, so the baseline 3 applies.

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

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

States a specific verb (Read) and resource (a tool's public rating and recent reviews), so the agent knows exactly what comes back. It does not, however, distinguish itself from the sibling review_tool (the write counterpart), leaving that differentiation to inference.

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

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

There is no when-to-use guidance and no mention of alternatives such as review_tool for submitting a review. Usage is only implied by the tool name and the required 'tool' parameter.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds real operational context beyond that: the returned payload depends on run state (result when finished, status while running), which tells the agent this is a safe repeated-poll call. It does not describe failure/error behavior or any polling interval, which keeps it out of 5 territory.

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

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

One sentence, front-loaded with the action and resource, with the state-dependent return tucked in as a subordinate clause. Nothing is wasted and nothing important is buried.

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

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

With no output schema, the description carries the burden of explaining return values and does so at a high level (result vs status). It omits what a finished-but-failed run returns and whether the result is inline or by reference, which are minor gaps for a one-parameter read tool.

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

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

With a single parameter and 100% schema description coverage, the schema already documents run_id and its provenance (returned by run_tool, run_job or run_recipe). The description adds no additional meaning about the identifier, so the baseline 3 applies.

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

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

The description states a specific verb (fetch) and resource (a run) and clarifies the two things it can return: a result or a status. It is clearly distinct from the run-starting siblings (run_tool, run_recipe) though it never names them explicitly, so the reader must infer that this is the retrieval counterpart.

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

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

'or its status while it is still running' implies the tool can be called at any point in a run's lifecycle, which hints at polling usage. However, it never states when to prefer this over get_recipe/get_usage or that it should be called repeatedly until completion, so the usage guidance remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral value by disclosing the payload contents (views, per-item votes, leading option, comments) and scoping results to shares the caller owns.

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

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

A single sentence with zero filler, front-loading the action and resource before the return contents. Every clause earns its place.

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

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

With no output schema, the description usefully enumerates the returned fields, which is the main thing an agent would otherwise lack. It stops short of describing pagination, ordering, or error behavior for an invalid/stale share_id, but is otherwise sufficient for a one-parameter read tool.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents share_id and its origin from the 'share' tool. The description adds no format, syntax, or validation details beyond that, which is the expected baseline when the schema does the work.

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

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

Specific verb ('Read') plus resource ('a share link') and an enumeration of the returned content (views, votes per item, leading option, comments). This cleanly separates it from the sibling 'share', which is the create counterpart, so an agent can route without ambiguity.

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

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

The phrase 'a share link you created' implies the precondition that the share must already exist and belong to the caller, and implicitly points at the 'share' tool that produced it. There is no explicit when-not-to-use or named alternative, so guidance is implied rather than stated.

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

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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful shape information not in the annotations: key/job/tag rows carry their monthly limit, and grouping is controlled by a tag:<name> dimension.

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

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

Two dense sentences with no filler, and the primary grouping behavior is front-loaded. There is mild redundancy between the group enumeration in the first sentence and the schema's group description, but the sentence still earns its length.

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

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

For a read-only aggregation over six optional filters with a fully covered schema and no output schema, the description explains both the grouping axis and the filter dimensions adequately. Missing only minor operational detail such as row limits/pagination and the default time window, which the schema partially covers.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema, including the group dimension list and the tag syntax. The description restates the same group enumeration and tag example rather than adding syntax, defaults, or constraints beyond it; baseline 3 applies.

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

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

The description names a concrete resource and action ('Account spend grouped by...'), and enumerates the available grouping dimensions, so an agent knows exactly what is computed. It does not explicitly distinguish itself from nearby spend/viewer tools such as get_balance or compare_providers, so sibling differentiation is left to inference.

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

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

It conveys implied usage through the filter clause ('optionally filtered by tags, key or job'), which tells the agent this is a filtered aggregation query. However, it never states when to prefer this tool over get_balance or compare_providers, and offers no exclusions or prerequisites.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine value beyond that by disclosing the returned artifacts and the intended pre-execution workflow; it does not cover failure behavior for an invalid slug, which keeps it from a 5.

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

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

One sentence, zero filler, front-loaded with the returned artifacts and ending on the reason to call it. Every clause earns its place.

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

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

With no output schema present, the description correctly compensates by naming what the response contains (input schema, output schema, normalized schema, price, category). Only error/unknown-slug behavior is left unstated, which is a minor gap for a one-parameter read tool.

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

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

Single parameter with 100% schema description coverage ('Tool slug from search_tools, e.g. brasilapi.cnpj'), so the schema carries the semantics. The description adds no format or resolution detail beyond what the schema already provides, making 3 the correct baseline.

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

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

States a specific verb (get/inspect) and resource (a tool's input schema, output_schema, normalized_schema, price, category), enumerating exactly what is returned. An agent can distinguish it from search_tools (discovery) and run_tool (execution) from the text alone.

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

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

"before running it, so you can write the parsing code first" gives a clear temporal/conditional use case that implies run_tool as the follow-up action. No explicit exclusions or naming of the alternative tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds domain context (categories group providers by shared I/O format, making them comparable) but says nothing about ordering, completeness, or result shape.

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

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

A single short fragment with no filler; it is compact and front-loads the key concept. However, the lack of a subject-verb makes it read as an under-specified fragment rather than a clean, purposeful statement.

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

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

For a zero-parameter, read-only list tool this is close to adequate, and the definition of a category is genuinely informative. It still omits any statement that the tool returns a list of categories and gives no sense of output size or ordering, which would round out the picture.

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

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

The tool takes zero parameters, so the schema imposes no semantic burden and the baseline for this dimension is 4. No argument meaning exists to document.

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

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

The name and title ('list_categories'/'List categories') carry the action, but the description itself is a noun phrase that defines what a category IS rather than stating that this tool lists them. It offers no differentiation from siblings such as compare_providers or search_tools, leaving the agent to infer the verb.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. The phrase 'can be compared' faintly hints at a relationship with compare_providers, but the connection is never stated, so the agent gets no routing help.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context beyond the annotations: the exact fields surfaced (label, tags, monthly limit, spend this month) and, importantly, that secrets are never returned. It does not mention pagination or ordering, so not a 5.

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

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

A single tight sentence front-loads the resource and scoping, then layers the returned fields and the secrets caveat. No filler, nothing redundant.

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

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

With no output schema, the description usefully compensates by naming the returned fields and the secret-exclusion rule. For a zero-required-parameter read tool this is close to complete; only ordering/pagination behavior is unaddressed, which is minor.

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

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

Schema description coverage is 100% and the single parameter (include_revoked) is already documented in the schema. The description adds nothing about the parameter, so the baseline 3 applies; there is no gap for it to compensate for.

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

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

States a specific verb and resource (list API keys) and scopes it precisely to 'your API key and the keys it created', which tells the agent this is not a global key listing. It even enumerates the returned fields. It stops short of naming siblings like create_key/revoke_key/update_key to differentiate, hence 4 rather than 5.

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

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

Usage is only implied: a read operation for viewing your keys. There is no explicit statement of when to use this versus create_key, revoke_key or update_key, and no exclusions or prerequisites. The 'Never returns secrets' clause does imply a boundary (use this to inspect metadata, not to retrieve secret values), which lifts it above a total absence of guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral content beyond that: with no output schema, it discloses the returned fields (name, cost estimate, skill_url, script_url) and notes script_url is conditional on a recipe being official, which is useful shape information an agent cannot get elsewhere.

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

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

Two tight sentences: the first establishes what recipes are, the second enumerates the return payload with the conditional case parenthesized. No filler, no repetition of the title or annotations.

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

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

For a zero-parameter read tool with no output schema, the description supplies the domain framing and return-field list an agent needs to call and interpret it. Minor gaps remain (no statement of ordering, pagination, or filtering scope), but nothing essential is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level meaning is missing.

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

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

The description defines the resource domain (recipes are skills for common jobs built from Superpowers tools) and implies enumeration via the 'Returns name, cost estimate, skill_url...' clause, which reads as a listing of what each item contains. It is clear what the tool produces, but it never states scope explicitly (all recipes? all available to the caller?) nor contrasts itself with the sibling get_recipe, which fetches a single recipe.

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

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

There is no when-to-use guidance and no routing to alternatives. A sibling named get_recipe exists, yet the description never says to use list_recipes to discover recipes and get_recipe to fetch one, leaving the agent to infer the split from the names alone.

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

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

Beyond annotations, the description discloses that the call is free, explains the returned plan structure, links planned steps to run_tool via trace_id, and specifies a $0.50 cost notification rule. It does not cover error behavior or auth, but it is substantially more informative than the annotations alone.

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

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

The description is front-loaded with cost and purpose, then returns, workflow, and the cost-notification rule. Every sentence adds useful operational detail with no filler.

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

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

For a one-parameter planner with no output schema, the description fully explains what the tool returns, how to use the result, and when to surface cost to the user. An agent has enough information to select and invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents the sole goal parameter. The description adds a concrete example of an accepted multi-part goal, which meaningfully illustrates the parameter's expected semantics beyond the generic schema text.

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

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

The description states a specific resource (a goal) and returns (steps, tool per step, example input, per-step and total cost, and an existing recipe when available). It distinguishes this planning tool from execution by explicitly saying to call it before multi-step work and then use run_tool.

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

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

It gives explicit usage conditions: call it before multi-step work, then run_tool each step with trace_id = plan_id. It also handles the recipe case and adds a concrete cost threshold requiring user notification before execution.

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

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

Annotations already flag readOnlyHint=false and openWorldHint=true, and the description adds genuinely new behavioral context: the artifact is public by default, is visible to other people's agents, and requires a privacy check first. It does not mention whether republishing the same name creates a duplicate or overwrites, which matters given idempotentHint=false, but the main consequences are disclosed.

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

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

Three tight sentences: purpose first, payload definition second, visibility and privacy caveat last. No filler and no repetition of schema text.

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

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

Covers purpose, the required payload, and the visibility default, which is enough for an agent to call it correctly without an output schema. Minor gaps remain around what a successful publish returns (slug, URL, or nothing) and behavior on name collisions, but these are secondary for a creation tool whose parameters are fully documented.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra credit by explaining what skill_md must actually contain (what to ask, which tool slugs to call in what order, how to deliver) — semantics the schema's one-line "recipe steps as a SKILL.md document" does not convey. It also reinforces the public/private default.

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

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

States a specific verb and resource ("Save a job ... as a reusable recipe") and immediately clarifies the scope: it publishes something others can give their agents, which cleanly separates it from run_recipe, get_recipe, and list_recipes. It even pre-empts confusion about what the recipe artifact is by describing the skill_md payload.

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

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

Gives a clear situational rule: publish a job you already did, and ask before publishing anything containing client names or private details. That is real when-to-use guidance with a privacy guardrail, though it never names an alternative action (e.g., keep it private via `public: false` instead of not publishing).

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds genuinely non-derivable behaviour: the rating is publicly attributed (visible to other agents choosing tools and to the vendor), and a repeated review is an upsert that replaces the prior one. Missing are auth/prerequisite details and any rate-limit or moderation caveat.

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

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

Three short sentences that are front-loaded with the action and scale, then the consequence, then the upsert rule. Every sentence carries information the agent cannot get from the schema or annotations.

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

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

For a simple 3-parameter tool with no output schema and full annotation coverage, this covers the action, scale, audience, and repeat-call semantics well. It stops short of stating preconditions (ownership of the run, whether the tool must have been invoked) that an agent would want before calling.

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

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

Schema coverage is 100%, so the fields are documented, but the description still adds intent beyond the schema: the comment should say 'what was good or wrong', which shapes what content to supply in a field the schema only labels 'Optional short comment'. The rating scale is repeated from the schema rather than extended.

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

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

States a specific verb and object ('Rate the output of a run, 1-5 stars') plus the optional comment, so the action is unambiguous. It does not name a sibling to distinguish itself from close neighbours like send_feedback or get_reviews, and the name/title ('Review a tool') versus the body ('output of a run') creates a slight tool-vs-run ambiguity.

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

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

Usage is implied rather than stated: the phrase 'output of a run' suggests this is called after run_tool/run_job/run_recipe, and the description explains why a rating matters. However, there is no explicit when-to-use/when-not, no named alternative (e.g. send_feedback), and no preconditions such as whether the run must be your own.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's added value is the cascade rule ("Keys it created are revoked too") and the immediate operational consequence ("Agents using it stop working right away") — exactly the kind of blast-radius information an agent needs before a destructive call. It does not address re-revoking an already-revoked key, which is relevant given 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.

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

Three short sentences, no filler, with the permission scope and the cascade warning front-loaded ahead of the impact statement. Every sentence carries distinct information.

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

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

For a single-parameter destructive tool with a fully documented schema and annotations covering the safety profile, the description covers scope, cascade and immediate effect. Only minor gaps remain (error behavior for unknown/already-revoked keys), and no output schema means return values need not be explained.

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

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

With 100% schema coverage and a documented key_id pointing at list_keys/create_key, the schema already carries the semantics. The description adds no format hints or edge-case notes about key_id, so baseline 3 applies.

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

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

Specific verb+resource ("Revoke a key") that cleanly separates it from create_key, update_key and list_keys in the sibling set. The clause "a key you created (or your own)" scopes which keys are eligible, though it stops short of explicitly naming the alternative tools.

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

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

Usage context is only implied: the ownership clause tells the agent it can revoke self-created or self-owned keys, which implicitly signals the permission boundary. There is no explicit when-to-use/when-not guidance and no pointer to update_key as the non-destructive alternative.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare the operation is a non-destructive write in an open world. The description goes beyond that by disclosing the charge threshold requiring user confirmation, the returned fields (charge_usd, per-step output, share_url), and the intended UX for the share link. It does not address idempotency/retry semantics, which the schema covers instead.

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

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

Four sentences, front-loaded with the core action, then cost gating, then return/UX instructions. Tight and useful, though the trailing guidance about the share link is slightly run-on.

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

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

There is no output schema, and the description compensates by naming the return shape (charge_usd, step outputs, share_url). Combined with the cost-confirmation rule and the recipe-slug source (list_recipes), an agent has enough to invoke and report correctly, though the inputs object semantics remain delegated entirely to the schema.

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

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

Schema description coverage is 100%, so the schema documents recipe, inputs, review and idempotency_key in detail. The description adds only an indirect reference to estimated_cost_usd from list_recipes/get_recipe; it adds no syntax or constraints beyond the schema, making 3 the correct baseline.

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

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

States a specific verb+resource ('Run an official recipe on our servers in one call'), which is concrete and distinguishable from run_tool/run_batch by the 'recipe' object. It does not explicitly contrast itself with those siblings, so it stops short of a 5.

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

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

Gives one conditional workflow rule ('if estimated_cost_usd ... is above $0.50, tell the user before running it'), which is useful context. However it never states when to pick run_recipe over siblings like run_tool or run_batch, so the when-to-use guidance is only implied.

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

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.

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.

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.

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.

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.

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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral detail beyond them: semantic ranking, empty-query behavior, the return payload (slugs, prices, quality stats, total, has_more), pagination mechanics, and the actionable status rule that "degraded" means the vendor is paused until unavailable.available_at.

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

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

Dense but front-loaded: purpose, then matching semantics, then return shape, then pagination and status handling. One sentence is garbled ("status 'degraded' means the vendor is paused until unavailable.available_at"), which costs a bit of clarity, but there is little wasted text overall.

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

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

With no output schema, the description correctly documents the return fields, totals, and pagination contract, and covers the degraded-status edge case. The status sentence is confusingly worded, which slightly weakens an otherwise complete picture for a search tool.

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

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

Schema description coverage is 100%, so the schema already defines all three parameters. The description goes beyond it by explaining how query is interpreted (matching by meaning, vendor/model names ranked first, empty string lists all tools) and by tying offset to next_offset from the prior page.

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

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

States a specific verb (search/find) and resource (marketplace tools) with the mechanism spelled out: plain-language, meaning-based matching. It is immediately distinguishable from siblings like inspect_tool, run_tool, and list_categories.

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

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

Gives clear usage context: empty query lists every live tool, name a vendor/model to rank it first, and paginate via next_offset when has_more is true. It stops short of naming sibling alternatives (e.g. list_categories or inspect_tool) or stating when not to use this tool, so it is strong context without explicit exclusions.

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

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

Annotations only mark this as a non-read-only, non-destructive, non-idempotent, non-open-world write. The description adds genuinely useful disclosure: the feedback is routed to the vendor behind the tool and to the Superpowers team, and it is private. It omits any note on rate limits or irreversibility of submission.

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

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

Two sentences, front-loaded with the core action and destination, followed by the run_id conditional and the privacy note. Every clause carries distinct information with no filler.

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

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

With no output schema, the description sensibly covers the destination and privacy of the submission, which is the main thing an agent needs to know. It is complete enough for a submission tool, though it does not say whether anything is returned or acknowledged.

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

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

Schema coverage is 100%, so all five parameters are already documented, and the enum for type is spelled out in the schema. The description only marginally extends this by explaining when to supply run_id and what missing_tool signifies, which keeps it at the baseline for high-coverage schemas.

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

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

States a specific verb (send) and resource (private feedback) and enumerates the accepted kinds of feedback, including the missing_tool case. The phrase 'Not shown publicly' implicitly distinguishes it from review_tool, so an agent can tell it apart from siblings.

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

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

Gives a concrete conditional for the optional run_id ('Pass run_id when it is about a run') and clarifies the missing_tool type, which is clear usage context. It stops short of explicitly naming review_tool as the public alternative, so the when-not is only implied by 'private'/'not shown publicly'.

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

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

Annotations only cover the mutation/open-world profile; the description adds what matters: links are unlisted but publicly viewable, so secrets and personal data must be excluded, and a pre-publish confirmation step is required for unrequested pages. It also discloses that review=true turns the page into a vote and that local files must be uploaded first.

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

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

Front-loaded with the capability and cost ('Free'), then the review flag, then item shape, then the offering policy. Dense but nearly every sentence carries actionable policy; the offering etiquette paragraph is long but justified for a user-facing publish action.

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

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

For a 6-parameter mutation with no output schema, it covers the prerequisites, the public-visibility risk, and when to act, with 'a clean link' implying the return value. It stops short of describing what the returned link/identifier looks like or whether links can be revoked or expire.

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

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

Schema coverage is already 100%, so the schema carries the field-level meanings; the description adds cross-tool semantics the schema cannot, namely the upload_file prerequisite for local files and passing a recipe when one was followed. It does not explain the interaction between review and question beyond what the schema already says.

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

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

States a specific verb and resource ('publish files, images, video, audio or text as a clean link') plus the key outcome (anyone can view, no account needed). This clearly separates it from read-side siblings like get_share or get_reviews.

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

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

Gives explicit trigger conditions (user choosing between options, mentioning a client/boss/team/partner, wanting to send or show something) and an explicit exclusion ('Otherwise don't bring up sharing'). Also sets a frequency norm ('once per deliverable, in one short sentence').

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

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

The annotations already flag the tool as destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the description does not need to establish that it is a mutation tool. Beyond that, it adds useful policy context the annotations cannot express: limits can only be lowered, a key cannot retag itself, and a child key inherits its parent's tags. It does not explain what happens to existing runs when tags change, but the added constraints are substantial.

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

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

It is two sentences with no wasted words. The capabilities come first and the constraints come second, so the important behavior is front-loaded and easy to scan.

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

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

For a 4-parameter mutation tool with no output schema, this description is nearly complete: it explains which fields are updatable, which limits cannot be raised, and how tags interact with child keys. It lacks only secondary details such as the response shape or whether renaming has side effects; those are not required for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema: it clarifies that monthly_limit_usd can only be lowered through this tool, which the schema does not state, and that tags can only be changed on a key you created. It also implies that label is a rename, which helps an agent map the label field to its effect.

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

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

The description names a specific verb set and a specific resource: rename, retag, or lower the limit of a key. It clearly describes the three fields this tool can mutate, which distinguishes it from other siblings such as create_key, list_keys, and revoke_key. It does not explicitly name those siblings, so it falls short of full differentiation, but its scope is clear.

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

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

It clearly states what this tool can do and what it cannot do: "Keys can't raise limits or change their own tags." Those exclusions tell an agent when to stop and look elsewhere, for example to create a new key with a higher limit. It does not name an explicit alternative tool for those operations, so it is clear but incomplete.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the 200 MB ceiling, the re-host vs. local-bytes distinction, and the raw-HTTP escape hatch. It does not acknowledge non-idempotency or state that each call yields a new hosted artifact, which is the remaining behavioral gap.

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

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

Two sentences, both front-loaded with the highest-value information (size limit and destination first, mode selection second, fallback last). No filler or restatement of the tool name.

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

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

Covers input modes, size limits and the out-of-band path, which is what an agent needs to invoke it correctly. With no output schema, the description arguably should mention that the call returns a hosted/shareable URL, and it does not state auth or permissions; those are the only omissions.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine semantics: 'url' is for re-hosting an existing remote file while 'base64' requires pairing with 'filename' for small local files. That pairing rule and the size threshold are not expressed in the schema itself.

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

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

States a specific verb+resource ('upload_file' / 'Free file hosting... for sharing') and quantifies scope with the 200 MB cap. It also names the two supported input modes, so an agent immediately understands what the tool accepts and produces; no sibling in the list does anything comparable, so no differentiation is needed.

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

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

Explicitly routes the agent: 'Pass url to re-host a remote file, or base64 + filename for small local files,' and gives the exclusion case with a concrete fallback ('For big local files use: curl -F file=@path <base>/v1/files'). Both when-to-use and when-not-to-use are covered with actionable alternatives.

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