livepair-hub

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

Annotations only declare the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false); the description goes far beyond that, disclosing the x402 settlement flow, the PAYMENT-SIGNATURE retry mechanism, the returned shape {choices, usage}, the anonymity/metering policy, and the exact pricing formula. This is exactly the kind of behavioral detail an agent needs before triggering a paid call.

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 in the first clause, and the dense em-dash style packs model coverage, payment mechanics, pricing, and anonymity into few sentences. It is packed but nearly every clause carries distinct operational information, so little is wasted.

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 uncharacteristically covers the return shape ({choices, usage}), the full payment lifecycle, the billing formula, and the absence of accounts/auth. For a 4-parameter paid tool, this leaves no material gap an agent would need filled 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 baseline would be 3, but the description adds meaning the schema lacks: the price formula ties prompt (input tokens) and maxTokens (output rate) directly to cost, reinforcing the 'set max_tokens tight to bill tight' advice. It also surfaces the model enumeration source for the model parameter.

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 ('paid endpoint for OpenAI-compatible chat completions'), names the model families served, and points to the model list under GET /v1/agent/models. It clearly distinguishes this text tool from siblings like generate_image and list_models.

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 payment precondition is spelled out (endpoint answers 402, wallet layer settles and retries), which is essential usage context, and the model list is referenced for discovery. However, there is no explicit when-to-use/when-not guidance relative to siblings such as quote_price or recommend_model, and no statement on when a paid call is preferable to 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description is consistent with a safe, non-destructive rewrite. It adds the useful detail that the rewrite targets a specific structured form, but says nothing about the shape of the returned prompt, its length, or token/rate constraints, which matters because no output schema exists.

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 defines the transformation and its output, the second gives the workflow cue. No filler, and the core purpose is front-loaded.

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 two-parameter, no-output-schema preprocessor this covers purpose and sequencing adequately, and names the structural fields the rewrite produces. It is slightly thin on the mode parameter's effect on the rewrite, which is the one piece of behavior an agent must get right.

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 both parameters are already documented, and the description adds no syntax or usage detail for either. Notably it never mentions the 'mode' parameter (t2i/i2i/t2v/i2v) that determines whether the rewrite is tuned for text-to-image, image-to-image, or video, even though that choice materially affects the result.

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 ('Rewrite a rough prompt idea') and names the concrete output structure (subject, composition, style, negatives), so it is clearly not a retrieval tool like get_prompt or search_prompts. It does not, however, explicitly contrast itself with those closest-named siblings, so it falls just short of the top mark.

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?

'Use before generate_image — better input, better output' gives clear sequencing guidance and names the tool it feeds. There is no statement of when NOT to use it (e.g. when the prompt is already structured, or that it does not generate anything itself), so it is clear context without 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?

Goes well beyond the annotations: it discloses the 402/x402 payment handshake, USDC on Base mainnet, per-call pricing with per-second video billing, the required client class, and the return shape ({status:'done',url} vs a jobId for polling). This is exactly the kind of behavior (cost, auth header, async fallback) that readOnlyHint/openWorldHint 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-loaded with purpose, then payment mechanics, then return behavior; every sentence carries information. It is dense with parentheticals and a long middle sentence, but nothing is 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 compensates by describing both success and async return shapes and the polling path. Combined with annotations and full schema coverage, an agent has everything needed to invoke and recover from this tool 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 description coverage is already 100%, so the baseline is 3. The description adds real meaning on top by linking duration and resolution to per-second, per-model video billing, clarifying the cost consequence of those parameters rather than restating them.

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 ('Render an image or video with a catalog model') and enumerates the supported modes (t2i, i2i, t2v, i2v), immediately separating it from read-only siblings like list_models, get_prompt, or trending_prompts. The reference to the private model line flagged private=true in list_models ties it explicitly to a sibling 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?

Gives clear operational context: it is a paid call, the endpoint first returns HTTP 402, and the caller must retry with a PAYMENT-SIGNATURE header using an x402-capable client, then poll a jobId for slow jobs. It routes to enhance_prompt (in the prompt param) and list_models (in modelId), though it does not state explicit exclusions or when NOT to use this tool versus quote_price/recommend_model.

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, non-destructive profile, so the bar is lower; the description still adds real value by noting the call is 'free' (contrasted with the paid generate endpoint) and by sketching the return states. It doesn't mention polling cadence or rate limits, so it is not exhaustive.

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 compact sentences, zero filler, front-loaded with the action and its cost characteristic before the return shape. 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 compensates by naming the three terminal/running states and the url field on success. That is nearly complete for a simple poller, though pagination/retry semantics 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 100% and there is a single jobId parameter fully documented in the schema. The description adds no syntax or format detail beyond what the schema already 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 ('check a running job') and ties it to its origin ('returned by the paid generate endpoint'), which pins down exactly which resource this operates on. It does not explicitly name a sibling alternative, so it falls short of the 5 bar for differentiation.

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?

'Check a running job returned by the paid generate endpoint' clearly places this in the post-generate polling workflow and signals when to invoke it. There is no explicit when-not or named alternative, but the usage context is unambiguous.

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 establish a safe read-only, non-open-world profile. The description adds real behavioral context beyond them: packs are rebuilt daily, counts reflect actual paid runs, and it silently falls back to a live topic search when no pack matches. No contradiction with annotations.

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 with no filler, front-loaded with the core resource definition and the theme enumeration before the fallback behavior. The parenthetical theme list is dense but earns its place since the schema has no enum.

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 return-value burden and does so partly by describing what a pack contains (curated picks with real paid-run counts) and the fallback path. It omits any mention of the limit parameter's effect, which is the main remaining 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 50%: topic is documented in the schema, limit is not, and the description never explains limit. The theme list does broaden the meaning of valid topic values beyond the schema's single example, but the gap for limit keeps this at 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?

Clearly states what the tool returns: a themed bundle of curated prompt picks, with an explicit theme list and a named fallback to live topic search. It distinguishes itself functionally from search_prompts, though it does not name that sibling 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?

The fallback sentence implies when the tool is useful (curated, high-signal picks per theme), but there is no explicit when-to-use statement versus search_prompts or trending_prompts. Usage must be inferred from the theme list and fallback clause.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered by structured data. The description adds real value beyond that by disclosing the return payload (verbatim prompt, model, result media, like/view counts, and a studio link that preloads the card), which matters because there is no output schema.

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 verb and resource, then the payload as a compact list. No filler, no restatement of the 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?

For a one-parameter read tool with annotations covering safety and no output schema, the description supplies the missing return-shape information and the id source via schema. It lacks any note on failure behavior for an unknown id, which is the only notable 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 description coverage is 100% and the single id parameter is documented with its source (search_prompts or trending_prompts). The description adds only 'by id' and no additional format, prefix, or validity detail beyond the schema, 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 ('Fetch one community prompt card by id') and then enumerates exactly what the card contains, so the agent knows what it gets back. It is clearly distinguishable from the sibling search_prompts and trending_prompts, which return collections rather than a single card.

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 'by id' implies this is the single-item retrieval path after a search, and the id parameter's schema note points at search_prompts/trending_prompts as the source. However, the description itself never states when to use this instead of a sibling, what to do if the id is unknown, or any prerequisite. Usage 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?

Annotations already establish the safe-read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description goes beyond them by explaining the semantics of the 'private flag' — that i2i/i2v source images must be AI-generated or owned and real-person photos require consent — which is genuine operational 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?

A single front-loaded sentence that opens with the verb and gets to the payload immediately. The nested parenthetical about private models is dense but every clause carries information, so nothing is wasted.

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 and no parameters, the description carries the full burden and discharges it by enumerating the returned fields and their meanings. An agent knows what it will get back and how to interpret the private flag without any other source.

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 per the rubric the baseline is 4. The description instead documents the shape of the returned fields, which is useful but belongs to output rather than parameter semantics.

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 ('List') and resource ('the public image and video generation catalog') and even enumerates the returned fields (id, label, mode, generation time, private flag). This clearly separates it from a tool like recommend_model, though it never names or contrasts any sibling 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?

The description never says when to reach for this tool versus alternatives such as recommend_model, nor does it state any prerequisites or exclusions. Usage is only faintly implied by the word 'catalog'.

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 safe-read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower; the description adds real value by disclosing the pricing formulas (flat per image call, per-second × duration at resolution tier) and guaranteeing the number matches what x402 would charge. It stops short of auth/permission or failure behavior for invalid model+setting combos.

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 core promise (exact price), followed by the pricing rules and the re-quote guarantee. Every clause earns its place with 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?

With no output schema, the description correctly indicates the return is an exact USDC amount, and annotations cover safety. It is slightly thin on edge cases — unsupported model/setting combinations or whether the quote is TTL-bound relative to the later charge — but otherwise complete for a read-only pricing 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 coverage is 83%, so the schema already carries most parameter meaning and the baseline is 3. The description adds an interaction the schema doesn't spell out — duration and resolution jointly drive video pricing — though it leaves aspectRatio and the payer discount interplay to 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?

States a specific verb and resource — 'Exact USDC price for a model+settings combo' — plus the scope ('before paying'), so an agent knows this is a pre-flight pricing lookup, not a generation call. No sibling overlaps this capability, making the distinction unambiguous.

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 paying' implies the usage context, and the note that the x402 endpoint re-quotes from the body hints that this is a preview. But there is no explicit when-to-use statement, no prerequisite (e.g. must have modelId from list_models), and no named alternative — routing guidance is left 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 read-only, non-destructive, closed-world operation. The description adds useful behavior beyond that: it returns a modelId, and private:true restricts to the private AI model line (i2v). It does not cover edge cases like no match, but with annotations in place this is solid.

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 one compact sentence plus a parameter note, front-loading the action and return value before listing selection criteria. Every clause is relevant.

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?

No output schema exists, so the description must explain the return value; it does so by stating it returns the modelId for generate_image. With annotations covering safety and schema covering parameters, the definition is complete enough for an agent to call 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 baseline is 3. The description adds meaning beyond the schema by explaining private:true as restricting to the private AI model line (i2v models) and by summarizing the goal/media/source-image combinations, though it mostly mirrors the enum values.

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 action (decide/recommend) and resource (model), gives the concrete output (modelId), and ties it to generate_image. It makes clear this is a selection helper, not a generator or lister, so an agent can distinguish it from generate_image.

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 tells when to use the tool: to choose a model for generate_image based on goal (cheapest/fastest/best_quality), media (image/video), and source-image presence. It does not explicitly say when not to use it or name list_models as an alternative, 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?

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered; the description adds real behavioral value by naming the return payload (prompt text, model, result media, run link), which matters since no output schema exists. It stops short of describing result ordering, pagination, or whether results are cached/indexed, so it is not fully transparent.

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, each earning its place: purpose, routing rule, return shape. The corpus definition is front-loaded and there is no redundant restatement of the name or schema.

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 compensates by summarizing the returned fields and by pointing to the sibling for the trending case. For a simple three-parameter read tool this is nearly complete; only result ordering and any rate/indexing caveats are unaddressed.

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 query, kind, and limit are already documented in the schema, making 3 the baseline. The description only loosely echoes the query semantics ('style/subject/model lookups') and says nothing about the kind enum values or the limit ceiling beyond what the schema states.

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 ('Keyword search over the community prompt library') and immediately scopes the corpus ('tested AI image and video prompts with the results they produced'). It explicitly distinguishes itself from the sibling trending_prompts, so the agent can route without opening either 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 positive guidance ('Use for style/subject/model lookups') and an explicit exclusion with the alternative named ('For trending or most-used prompts call trending_prompts instead'). Both the when and the when-not are stated rather than 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context the annotations lack: results are community prompts ranked by paid generations driven, i.e. the ordering is popularity-based rather than relevance-based. It stops short of describing result freshness, pagination, or what a 'prompt card' 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 sentences, zero filler, and the usage trigger is front-loaded before the return-value explanation. Every clause earns its place by either routing the agent or describing the output.

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 carries the burden of explaining returns, and it does name the return type and ranking criterion. Minor gaps remain: no mention of how far back 'trending' looks, result freshness, or what fields a prompt card exposes.

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?

Only one parameter (limit), and schema coverage is 100% with a description already stating the default and max. The prose adds no additional meaning about the parameter, 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 and resource ('Returns community prompt cards') plus the ranking basis ('ranked by the paid generations they actually drove'), which cleanly separates it from search_prompts, get_prompt, and list_models. An agent can identify the tool's output shape 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 explicit trigger phrasings ('trending, most-used, most popular, or top prompts') and an explicit negative routing rule ('do NOT keyword-search for these'), which steers the agent away from the sibling search_prompts. Both when-to-use and when-not-to-use are covered.

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