VNGRD// creative toolkit

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the description isn't carrying the safety burden. It does add behavior the annotations cannot: the per-call price and currency, the x402 payment mechanism, and the failure mode of an unpaid call returning payment requirements. It does not say whether repeated calls yield the same or a fresh randomized bassline, which matters 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?

Two tight sentences: the deliverable first, then the commercial/transport condition. Nothing is padded, and the most decision-relevant facts (what you get, what it costs, how to pay) are 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?

There is no output schema, but the description compensates by enumerating what the JSON contains (notes, rests, holds, accents, slides, filter settings) and stating it is sequencer/synth-consumable. Combined with the payment detail this is close to complete for a three-parameter generator; the main gap is tempo/bpm semantics and determinism.

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 0%, so the description needs to explain all three inputs and it only partially does. Key and scale are covered indirectly ("any key, minor or major" matches the minor/major enum), but bpm is never mentioned at all, nor are valid ranges, note that bpm controls tempo of the generated pattern, or how the default key A interacts with the scale.

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 the exact artifact produced: a 16-step acid bassline with notes, rests, holds, accents, slides, in any key/scale, plus filter settings, emitted as JSON. That is specific enough to separate it from the other audio siblings (vngrd_beat, vngrd_voice, vngrd_cover_art) without opening any 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?

Usage context is implied rather than stated: an agent can infer you call this when you need a playable bassline pattern. The one piece of explicit operational guidance is the payment flow (send payment in _meta["x402/payment"], otherwise you get the payment requirements back), which is genuinely useful. There is no when-not-to-use guidance or comparison to a sibling like vngrd_beat.

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 behavior the annotations do not cover: a fixed $0.02 USDC cost on Base, the x402 payment mechanism, the exact _meta["x402/payment"] key, and the fallback that an unpaid call returns payment requirements rather than failing. It does not disclose whether successive calls produce different patterns, which matters 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?

Two sentences, front-loaded with what is produced and followed by the payment mechanics. Dense but every clause carries information; the style list inside the first sentence is the one mildly redundant element against the 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?

For a low-complexity two-parameter generator with no output schema, the description gives the output form ('JSON any sequencer can play') and the full payment flow, which is the main risk of a wrong call. It would be stronger with a hint at the returned structure and whether output varies per call, but nothing essential 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 0%, so the description carries the burden. It enumerates the four styles (matching the enum, so redundant) but never mentions the bpm parameter, its default of 120, or any sensible range. With only two parameters and one of them unaddressed, the description only partially compensates for the schema gap.

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 concrete resource and its exact contents: a 16-step drum pattern covering kick, snare, hats, open hat and clap, with velocities and swing, in four named styles. An agent can tell this apart from vngrd_bassline without opening a schema. It stops short of explicitly contrasting itself with the paid siblings, so not quite 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?

Usage is only implied: you call it when you need a drum pattern. There is no statement of when to prefer vngrd_bassline or vngrd_catalog, and no exclusion or prerequisite beyond the payment requirement. The payment instruction is procedural guidance, not selection 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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the call costs nothing, and downstream payment runs over x402 with USDC on Base — information an agent needs before deciding to proceed.

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 short sentence, front-loaded with the cost signal ("Free.") that matters most for an agent deciding whether to call it. Every clause adds distinct information — inventory, price, return payload, payment rails — with no repetition 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?

With no output schema, the description carries the burden of describing returns, and it does so at field level (each tool, its USDC price, what it returns, how to pay). It stops short of describing the response shape or ordering, but for a zero-parameter catalog that is a minor omission.

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. The description correctly implies a parameterless call and spends no words on nonexistent inputs.

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?

"Lists every VNGRD tool with its price in USDC, what it returns, and how to pay" names a concrete verb (lists), a concrete resource (VNGRD tool catalog), and the exact fields returned. Against siblings like vngrd_voice or vngrd_transcribe, it is unmistakably the discovery/metadata tool rather than a generation 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?

Leading with "Free" signals the natural usage pattern: call this first to inspect prices and payment mechanics before invoking a paid sibling. However, it never explicitly states that sequencing or names any sibling as an alternative, so the routing logic is inferred 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?

Goes well beyond the annotations by disclosing the exact payment mechanic ($0.05 USDC on Base via x402, sent in _meta["x402/payment"]), what happens on an unpaid call (returns payment requirements), and the 7-day retention of the returned image link. It also notes that the title only steers mood and no text is drawn, which prevents a predictable misuse.

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 outcome, then format, then price and payment mechanics, so the most important information arrives first. It is dense with parentheticals and would read better split into short sentences, but no sentence 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?

There is no output schema, and the description compensates by stating the return value (a link to a PNG/JPEG, retained 7 days). Combined with the payment flow and the aspect/appearance options, an agent has everything needed to call this correctly on the first attempt.

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 schema coverage at 75%, the description adds real meaning for otherwise thin parameters: the enum on `aspect` is restated as a user-facing choice of picture shape, and the `title` parameter's non-obvious behavior (mood steering, no text rendered) is spelled out here rather than in the schema. The `look` enum values are still only labeled 'Art direction' in the schema and are not elaborated in the description.

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?

Uses a concrete verb+resource pair ('Original artwork for a release, a single, a playlist, a video thumbnail or a channel') and enumerates the supported output shapes. It is clearly distinguishable from siblings like vngrd_voice, vngrd_subtitles and vngrd_bassline, which all produce different media.

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?

Names the concrete situations the tool serves (release, single, playlist, thumbnail, channel art) and explains the payment precondition that governs whether a call succeeds. It stops short of explicitly ruling out cases or pointing to a sibling when a different media type is wanted, so it does not reach the top band.

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 openWorldHint=false, so safety is covered. The description adds real context beyond that: the cost ('Free'), the enumerated state space (queued, rendering, done, failed), and the conditional return of the video link only when done. It still omits what happens for an unknown or expired job_id.

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, front-loaded with the cost signal and then the return value. Nothing is padded and no sentence fails to carry 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 carries the return-value burden and does so by stating the state values and the conditional link. The remaining gap is the provenance of job_id, which matters for a tool whose entire input is an opaque identifier.

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 single job_id parameter has 0% schema description coverage and the description does not say where the identifier comes from, what format it takes, or whether it is reusable. With one undocumented parameter, the description should have compensated and does not.

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 resource (a music-video job) and what is returned (its state, plus the video link when done), which is enough to separate it from the generation siblings like vngrd_bassline or vngrd_cover_art. The verb is implied rather than stated, which keeps it just 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?

There is no explicit when-to-use guidance, no mention that job_id comes from one of the sibling generation tools, and no advice on polling after submission. The only usage signal is the leading 'Free', which implies it is safe to call casually but does not route the agent.

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, the description discloses the paid x402 flow, the specific _meta payment key, the per-call price, and what a call without payment returns. This is valuable behavioral context, though it does not say whether results return immediately or as a job that must be polled.

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 a tight, front-loaded block: capability and outputs first, limits next, payment mechanics last. Every sentence carries actionable 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?

For a paid, open-world media-processing tool with no output schema, the description covers deliverables and pricing well. It omits the execution model (synchronous versus job-based, typical latency, or how to retrieve files), which matters given the presence of vngrd_job.

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 both parameters are already documented, including the note that the original language is always included. The description adds little parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.

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: transcribes, times and translates a video or podcast into up to 3 languages and returns SRT and WebVTT files. That clearly distinguishes it from a plain transcription sibling like vngrd_transcribe, though it never names the alternative 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?

It gives useful operational context (15-minute and 20 MB limits, target platforms, payment requirement) but no explicit guidance on when to choose it over vngrd_transcribe or other siblings, and no when-not-to-use 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?

Beyond the annotations, it discloses the commercial model ($0.05 USDC on Base, per call), the exact payment protocol (x402, payment passed in _meta['x402/payment']), and the failure mode when payment is absent (returns payment requirements). That is precisely the behavioral context an agent needs to invoke a paid endpoint without a failed 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?

Two sentences, front-loaded with capability and limits, with the payment mechanics last. It is dense but every clause carries actionable information; the payment sentence is somewhat packed with parenthetical detail, which costs it a point.

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 compensates by naming the return payload (text, timed segments, SRT file). Combined with input constraints, format list, and payment semantics, an agent has everything needed to call it correctly and anticipate 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: language is optional and exists to skip auto-detection, and audio_url is a public https link accepted across mp3/wav/m4a/ogg/webm/mp4 (the schema does list formats, but the 'auto-detected by default' framing clarifies the default path).

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 ('Speech to text') with explicit scope (15 minutes, 20 MB, any auto-detected language) and enumerates the input types it handles. It does not, however, distinguish itself from the sibling vngrd_subtitles, which an agent could reasonably confuse with a transcript-plus-SRT 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 context for when to reach for it (podcast, interview, voice note, live set, video soundtrack) along with hard limits that determine eligibility. It stops short of naming when *not* to use it or routing to the sibling subtitle/voice tools, so selection between overlapping siblings still requires 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?

Beyond the annotations (readOnly=false, openWorld=true, non-idempotent, non-destructive), it discloses the output form and lifetime (an MP3 link kept 7 days), the exact cost ($0.03 USDC on Base), and the x402 payment mechanic including the failure mode when _meta["x402/payment"] is omitted. Those are precisely the operational facts an agent cannot infer from the annotation set.

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 use cases are front-loaded in the first clause, followed by constraints, return value, and payment terms in a logical order. The single dense sentence with semicolons is efficient, though the payment clause is long enough to slow scanning slightly.

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 covers the return value (MP3 link, 7-day retention) and the full payment handshake, which is essential for this tool to succeed on the first call. Remaining gaps are minor: no behavior stated for text exceeding 600 characters and no elaboration on the voice/language parameters.

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 only 33% schema description coverage, the description partially compensates: it states the 600-character ceiling (matching maxLength) and signals broad language support, hinting that lang accepts many ISO codes. However it says nothing about the `voice` male/female enum or the lang format, leaving the least-documented parameter unexplained in both places.

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 output (a spoken voice-over rendered as an MP3) and enumerates concrete use cases: intro, radio-style ident, promo, podcast line. That makes the verb+resource unambiguous and separates it in practice from vngrd_transcribe and vngrd_subtitles, though it never explicitly contrasts itself with those siblings by name.

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 enumerated scenarios (intro, ident, promo, podcast line) give a clear sense of when this is the right tool, and the stated 600-character cap plus per-call price act as practical applicability filters. It stops short of explicit when-not guidance or pointing the agent at an alternative tool for longer or non-voiceover needs.

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