Skip to main content
Glama

Soclo

by app.soclo
OverviewDiscussionsAdmin

Make one audio piece

soclo_audio_make
Destructive

Spends credits: makes one audio piece (music, sound_effects, voiceover in the line’s own language, or soundtrack). Read soclo_audio_quote first and pass its exact expectedCredits and pricingVersion so a moved price refuses uncharged. Show the owner the storyboard (soclo_host_plan_state) and the quote, and get their yes before a paid make; if the owner says "just make it", proceed through the remaining approved makes within the same ceilings without re-asking per piece, stopping if a price changes. Supply one stable clientRequestId per purchase: reconcile an unknown outcome under the same id with soclo_audio_recover and do not start a new paid request or mint a replacement id (duplicate_request means the earlier attempt was charged). For re-takes, re-read the quote and use a new clientRequestId; confirm debits in soclo_wallet. Pass the returned requestId, statusUrl, responseUrl and receiptId to soclo_audio_poll.

Input Schema

NameRequiredDescriptionDefault
modelYesmusic (a music bed) and sound_effects are priced by length; voiceover (speaks a line) and soundtrack (scores a described mood) have a flat price.
voiceNoFor voiceover: optional voice. Every voice speaks the line in the language it is written in.
promptYesFor make: the music/SFX description, or the exact spoken line(s) for voiceover.
durationNoFor music and sound_effects, within that model’s range: music 3-600 seconds; sound_effects 0.5-22 seconds. Fractional seconds are fine (music is priced per started minute). Use the value you quoted.
pricingVersionYesRequired for every make: from the quote.
clientRequestIdYesRequired for make and ID-only recover: persist one stable ID per purchase before submission. Recover that same ID after a lost acknowledgement; do not mint a replacement.
expectedCreditsYesRequired for every make: the exact figure from the server quote. Zero is valid only when the server quotes zero; Soclo checks the price again before charging.
ownerApprovedPriceYesRequired true for make only after the owner has seen the quote/flat price and said yes (or said "just make it" for this run).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / properties / duration / description
      Previous value: -"For eleven-metered makes, within the quoted model’s own range: eleven_music 3-600 seconds; eleven_sfx 0.5-22 seconds. Fractional seconds are fine (MAIN prices music per started minute). Use the value you quoted."New value: +"For music and sound_effects, within that model’s range: music 3-600 seconds; sound_effects 0.5-22 seconds. Fractional seconds are fine (music is priced per started minute). Use the value you quoted."
    • changedInput schema / properties / expectedCredits / description
      Previous value: -"Required for every make: the exact figure from the server quote. Zero is valid only when the server quotes zero; MAIN revalidates the price."New value: +"Required for every make: the exact figure from the server quote. Zero is valid only when the server quotes zero; Soclo checks the price again before charging."
    • changedInput schema / properties / model / description
      Previous value: -"eleven_music / eleven_sfx are server-quoted and metered; voiceover / soundtrack are flat-credit recipes."New value: +"music (a music bed) and sound_effects are priced by length; voiceover (speaks a line) and soundtrack (scores a described mood) have a flat price."
    • changedInput schema / properties / model / enum
      Previous value: -[
-  "eleven_music",
-  "eleven_sfx",
-  "voiceover",
-  "soundtrack"
-]New value: +[
+  "music",
+  "sound_effects",
+  "voiceover",
+  "soundtrack"
+]
    • changedInput schema / properties / voice / description
      Previous value: -"For voiceover: a vetted voice; defaults to Aria."New value: +"For voiceover: optional voice. Every voice speaks the line in the language it is written in."
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare destructive/openWorld/non-idempotent, and the description goes well beyond that: it discloses the credit charge, the price-drift refusal ("a moved price refuses uncharged"), required owner consent before a paid make, the approval-once-per-run exception, and idempotency semantics (duplicate_request means the earlier attempt was charged, never mint a replacement id). That is materially more than the structured fields convey.

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

Conciseness4/5

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

Front-loaded with the cost and purpose, and every sentence carries operational content (approval, pricing, idempotency, follow-up). It is a dense single paragraph with chained clauses, which is a bit heavy to parse, but there is little filler.

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

Completeness5/5

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

No output schema exists, yet the description still names the returned fields (requestId, statusUrl, responseUrl, receiptId) and tells the agent where to take them. Preconditions, pricing guardrails, retry/recovery behavior and approval gating are all present for what is otherwise a paid async mutation.

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

Parameters4/5

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

Schema coverage is already 100%, so baseline is 3; the description adds workflow meaning on top — expectedCredits/pricingVersion must be the exact quoted values, clientRequestId must be one stable persisted id per purchase, ownerApprovedPrice is only true after the owner sees the quote or says "just make it". It does not add much on model/voice/prompt/duration beyond what the schema states.

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

Purpose5/5

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

Opens with a specific verb and cost signal ("Spends credits: makes one audio piece") and enumerates the four model variants (music, sound_effects, voiceover, soundtrack), which lets an agent distinguish it immediately from soclo_audio_quote, soclo_audio_poll and soclo_audio_recover.

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

Usage Guidelines5/5

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

Explicitly routes the workflow: read soclo_audio_quote first, use soclo_audio_recover for unknown outcomes, re-read the quote plus a new clientRequestId for re-takes, check soclo_wallet for debits, hand the result to soclo_audio_poll. It also names the owner-approval condition and the "just make it" exception, so when-to-use and when-not-to-use are both covered.

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

All Soclo toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources