Private AI Media Generation

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

Annotations only supply generic hints (readOnlyHint=false, idempotentHint=false), so the description carries the real burden and does it well: it discloses that the call is PAID, the exact pricing formula, that metering retains token counts only, the auth header forms accepted, and the failure payload when no key is present. These are behaviors an agent cannot infer from the annotation block or the 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?

Information-dense and front-loaded — capability, then payment precondition, then pricing — with no filler sentences. The heavy em-dash parentheticals make it slightly cramped to parse, but every clause carries load-bearing content.

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 supplies the return shape ({choices, usage}) and the alternate payment-requirements response, plus the auth and billing model. Given four fully documented parameters and no nested objects, nothing an agent needs to call this 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 the baseline is 3, but the description adds real meaning by tying maxTokens directly to billing ('Price = ... max_tokens × output rate — set max_tokens tight to bill tight'), which the schema does not state. The model parameter is only cross-referenced to textModels rather than explained further.

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 operation and resource — 'OpenAI-compatible chat completions' over frontier and open-weight models — and tells the agent where the model list lives. This separates it cleanly from generate_image and the prompt/reference tools in the sibling set.

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 explains the two execution paths (key present → runs; key absent → 402 + x402 requirements) and advises setting max_tokens tight, which is genuine usage context. However, it never routes the agent to siblings such as quote_price for a cost preview, recommend_model for model choice, or list_models for enumeration, and gives no when-not-to-use condition.

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?

Far exceeds what the annotations convey: it discloses that the call is PAID, explains the auth path (x-api-key / Bearer lp_…), describes the exact failure mode without a key (upstream 402 returning x402 USDC-on-Base payment requirements), and states the success shape ({status:'done',url} or a jobId to poll). Annotations only mark it non-read-only and non-idempotent; the description adds the cost, auth, and async-return behavior an agent needs.

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?

Purpose and mode list are front-loaded and every clause carries real information (modes, payment, auth, return). It is dense and dash/parenthesis-heavy, and the payment paragraph is long for a first read, but nothing is redundant padding for a tool this complex.

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, 11 optional parameters, and external payment/auth complexity, the description supplies exactly the missing pieces: return shape, jobId polling path, and the no-key 402 behavior. Nothing an agent needs in order to invoke or recover from this call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter coupling the schema documents only in isolation: which inputs a given mode requires (image-only for tools, image+image2 for face-swap, image+video for motion) and that prompt is unnecessary for mode=tool. That conditional dependency logic is genuine added value.

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 specific verbs and resources (render/transform an image or video) and enumerates the exact modes it covers (t2i, i2i, t2v, i2v, tool), including which input each mode consumes. It also names related siblings (list_models for the private=true line, get_job for polling), so an agent can distinguish it from chat_text or recommend_model immediately.

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 mode-selection rules: tool models take an image with no prompt, face-swap takes image + image2, motion models take image + video. It also routes the agent to siblings (list_models for modelId, enhance_prompt for prompt quality, get_job for polling, search_references for references), covering both when to use it and what to do alongside it.

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 genuinely new context beyond that: the required credential type (lp_ key) and how it is transmitted (x-api-key / Bearer), which an agent needs before calling.

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 dense sentence, front-loaded with what is returned and followed by the auth constraint. No filler and nothing that needs to be read twice.

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 telling the agent what comes back (balance and recent ledger), and it does. Auth requirements are also stated. Only marginal gaps remain, such as behavior on an invalid or missing key.

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 baseline is 4. The description correctly adds nothing parameter-related and instead spends its words on auth and return content, which is the right allocation.

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?

Names the specific resource and scope: the prepaid credit balance plus recent ledger for the API key on the current request. It's clear what the tool returns, though it doesn't explicitly contrast with any sibling — not a real risk here since the siblings (chat_text, generate_image, list_models) are in unrelated domains.

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: an agent can infer you call it to check remaining credit, and the description notes the auth precondition. There is no alternative tool to route away from, but no explicit 'use when' framing either.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, and the description adds genuinely useful context beyond them: the call is free and the terminal states are done/running/failed. It does not address the non-read-only flag (any side effects of polling) or whether job results expire, so it adds moderate value without resolving the gap the annotations leave open.

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?

Roughly fifteen words, front-loaded with the action and the return contract, with no filler sentences. Every clause (source of the job, cost, return states) carries information an agent needs.

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 polling tool with no output schema, the description adequately covers the return states and the relationship to generate_image. The remaining gap is operational — no guidance on how or how often to poll, or how long a finished job's URL stays valid.

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 single jobId parameter is already documented. The description's phrase 'returned by generate_image' barely sharpens the schema's own 'jobId returned by the generate endpoint', 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 ('Check a running job') and ties it directly to its producer ('returned by generate_image'), which cleanly separates it from generate_image and the other generation siblings. The return-shape clause further pins down what the call produces.

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 (poll a job you got from generate_image) and notes it is 'free', which helps an agent decide to call it rather than something else. It never states polling cadence, when to stop polling, or what to do on 'failed', so usage is 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 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 safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false). The description adds genuine context beyond them — 'Read-shared for everyone' discloses access scope — but does not mention pagination, ordering, or return 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 dense sentence, front-loaded with the resource definition and ending with the workflow. The illustrative examples (golden-hour, neon-night, noir-bw) earn their place by making 'cohesive look' concrete, though the sentence carries several distinct ideas.

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-param list tool with annotations covering safety, the description covers what a pack is and how to proceed after listing. With no output schema, it could say more about what is returned per pack (id/name), but the conceptual content of a pack is conveyed.

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 baseline is 4. Nothing in the schema needs compensating for; the mentions of pack and referenceIds describe other tools' inputs, not this one's.

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 resource — 'curated moodboards usable as generation references' — and defines what a pack actually is ('a cohesive look: lighting/grade/mood') with concrete examples. It clearly differentiates from siblings by naming the downstream tools (search_references, referenceIds) rather than leaving the agent to guess.

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 an explicit workflow: pick a pack for the user's intent, search inside it via search_references(pack), then pin chosen refs via referenceIds. It does not explicitly contrast against sibling get_pack, so the 'when to use this vs the other pack tool' boundary is left partly 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 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond structured fields: it names the return value (modelId) and explains that private:true restricts to the private AI model line (i2v models).

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 purpose and the returned artifact, then layers the option space efficiently. Dense but every clause maps to an actual parameter dimension, so nothing is wasted; slightly clause-heavy punctuation keeps it from a clean 5.

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, no-output-schema tool, the description covers purpose, the return artifact, and all parameter axes. It does not explain failure modes (e.g., no model matches the constraints), 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 coverage is 100%, so the schema already documents all four parameters, setting a baseline of 3. The description adds meaning on top, glossing media='tool' as upscale/background removal and clarifying private:true as the private i2v model line, exceeding the 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 (decide/recommend a model) and, crucially, the output contract: returns the modelId to use with generate_image. This distinguishes it from list_models and generate_image without needing to open 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?

Enumerates the decision dimensions (cheapest/fastest/best quality, image/video/tool, with/without source image), effectively telling the agent the contexts in which it applies. It stops short of naming alternatives or when-not-to-use conditions, so it is clear context rather than 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?

Goes well beyond the read-only annotations by disclosing key-dependent scoping ('with your lp_ key your own uploaded refs are included; without it only curated packs are searched') and the critical non-mutating behavior that this tool never attaches references. These are behavioral traits the agent could not infer from readOnlyHint 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?

Three dense sentences, front-loaded with the core capability before scoping and routing details. Nearly every clause is load-bearing, though the sentence structure is packed enough to require a careful read.

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 search tool with no output schema, the description covers scope, key-dependent behavior, the return ('candidate images/clips with preview urls'), the non-attach contract, and the correct next step. Nothing essential for correct invocation 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 100%, so the baseline is 3, but the description adds meaning: it explains what 'pack' scopes to and gives concrete semantic query examples ('warm golden diner', 'neon night street'). The lp_ key note further clarifies how results vary, which the schema does not convey.

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 ('semantic search over your media-reference library AND shared curated moodboards'), making the dual scope explicit. An agent can distinguish it from list_reference_packs (lists moodboards) and generate_image (attaches refs) 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?

Explicitly routes: use 'pack' to search inside one moodboard picked from list_reference_packs, and states the downstream flow — never attaches, discuss candidates, then pin chosen ids via referenceIds on generate_image. Both the alternative tool and the follow-on tool are named with their conditions.

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.