eroq — AI video, images, voice and music

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

With no annotations, the description carries the full behavioral burden and does meaningful work: it discloses the tool is free, that output is a non-executing DRAFT, that nothing runs until publish, and that run_flow requires the Studio plan. It omits auth/permission requirements and failure behavior, but the side-effect profile (nothing runs) is the crucial disclosure for a create tool and it is present.

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

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

Two sentences, front-loaded with the core action and the zero-cost fact, with the draft/publish constraint placed where it matters. It is dense rather than wasteful, though the long mid-sentence list of trigger types and engines makes the first sentence heavy.

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 create tool with no annotations and no output schema, the definition covers the essential facts an agent needs: what it makes, that the result is a draft, and how execution happens. It does not state the return value (e.g. a flow id) or auth needs, but the behavioral and routing information is otherwise sufficient.

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 beyond the schema by telling the agent what the 'description' parameter should contain — trigger, steps in order, engines (Clap, Claude/GPT/Gemini/Grok), formats, folders, platforms — and by enumerating the four trigger types the flow can start from. This goes past the schema's terse field definitions.

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 — 'Build a new eroq Flow' — and enumerates exactly what the flow is composed of (start trigger, renders, writing steps, folder, post). It also differentiates from siblings by naming run_flow as the way to execute it, so an agent can tell it apart from edit_flow and run_flow 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 clear context for use: it creates a DRAFT that does not run until published in the studio, and points to run_flow (Studio plan) as the execution path, which routes the agent between creation and running. It stops short of an explicit 'do not use this when...' or a direct comparison to edit_flow, so it is strong on context but lacks stated 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?

With no annotations, the description carries the full burden, and it delivers non-obvious behavior: the whole flow is rebuilt and its status resets to DRAFT, requiring a manual republish. It omits auth/permission requirements and any reversal behavior, but the rebuild-and-reset side effect is the key thing an agent needs to know before invoking a mutation.

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 cost and the core action, then examples, then the behavioral consequence. Every sentence earns its place with no waste.

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 2-parameter, fully-schema-documented tool with no output schema, the description covers the essential unknown — the draft-reset side effect and republish requirement. It could state what the call returns (e.g., flow id/status), but nothing critical 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 both parameters (flow id/name, plain-words change) are already documented in the schema. The description reinforces that `change` is free-form text via examples but adds no syntax or format detail beyond the schema 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 (change) and resource (one of the person's Flows) with concrete examples of the kind of natural-language edit accepted. It is clearly distinguishable from create_flow, run_flow, and make_edit without opening any sibling 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?

"Free." immediately signals this costs nothing, and the DRAFT/republish note tells the agent the operation is a meta-edit requiring a follow-up publish in the studio. It gives clear context but never explicitly names when to prefer it over siblings like make_edit or create_flow.

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?

With no annotations, the description carries the full burden and does so well: it discloses the cost model (no credits for invention), the entitlement requirement (rewriting is a paid-plan perk), and the exact failure mode (pay-as-you-go keys get a 403). It also describes what the music mode returns (idea, title, style, lyrics with section tags).

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 but front-loaded sentence that opens with the core action and appends cost/auth caveats, with a parenthetical for the music special case. Every clause carries information, though the mid-sentence em-dash nesting makes it slightly heavy.

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-optional-parameter tool with no output schema, the description covers purpose, the empty-input case, mode behavior and the cost/403 behavior. It stops short of stating the shape of the returned prompt for image/video modes, but that is a minor gap given the tool's simplicity.

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 and the kind enum are already documented, including that prompt 'may be empty for a surprise' and what music mode returns. The description largely restates this, adding only the empty-draft behavior in slightly more operational terms, 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 pair (rewrites/invents) and resource (image or video prompt, or song for music), which is clearly distinct from the sibling generators like generate_image, generate_music and generate_video that produce media. It does not explicitly name those siblings, so the distinction is implied rather than spelled out.

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 the conditions for inventing (empty draft, free) versus rewriting (draft present, paid-plan), which is useful behavioral context. However, it never says when an agent should call this instead of going straight to generate_image/generate_video, nor whether the result is meant to be fed into a generation call — the usage path must be 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?

With no annotations provided, the description carries the full burden and does well: it discloses that renders cost credits, enumerates per-model credit costs and tier gates (creator+/hobby+), and states that it blocks until the render completes and returns the picture plus a stored link. It omits auth/error behavior, keeping it just short of a 5.

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

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

The core sentence is front-loaded and the return-behavior sentence is useful. The inline model enumeration is long and somewhat list-heavy, but each entry (cost + tier) carries information an agent needs for selection, so it largely 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?

There is no output schema, and the description compensates by describing the return (the image plus a link kept in the eroq library). Combined with cost, model options, and blocking semantics, it is nearly complete for a 5-parameter generation tool, with only auth/error details 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. The description goes beyond the schema by attaching credit cost and access-tier information to each model enum value, which the schema itself does not provide, adding real decision value for model choice.

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 ('Render one image from a text prompt') and bounds the scope to a single image. This clearly distinguishes it from siblings like generate_video, generate_music, and get_image_status, which polls rather than renders.

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 use case (produce an image from a prompt) is implied by the description, but it never states when to prefer this over siblings such as make_edit, enhance_prompt, or run_flow, nor when not to use it. Usage is inferable but not spelled out.

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?

With no annotations, the description carries the full burden and does so: it discloses async behavior, expected latency, brief inline waiting, credit cost scaling by requested length, the pricing model (3 cr per started 30 s), and the polling fallback. That is exactly the behavioral context an agent needs before a paid, slow operation.

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

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

Dense but front-loaded: purpose, modes, cost, and polling each appear in a short clause with no filler. The parenthetical model/pricing clause is slightly compressed but still 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?

For an async, credit-consuming generation tool with no output schema, the description supplies everything an agent needs: latency expectations, cost model, both input modes, and the status-polling continuation path.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: it distinguishes prompt-only from style+lyrics composition, explains section-tag line placement, and ties `seconds` to billing. Only partially overlapping with schema text, so it earns above 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 and resource ('Make a song with vocals and instruments') and immediately disambiguates the scope with 'async' and 'a few minutes.' An agent can distinguish it from generate_image/generate_video/generate_speech without inspecting 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?

Explicitly lays out the two invocation modes (single `prompt` versus your own `style` + `lyrics`) and the follow-up path ('poll get_music_status with the returned id'). It stops short of stating when to prefer a sibling like generate_speech, but within-tool routing guidance is clear.

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?

With no annotations, the description must carry the behavioral burden, and it does disclose that output is MP3 and that the call costs credits per 100 characters — genuinely useful context. But the credit amounts are left as literal '? cr' placeholders, and there is no mention of auth requirements, rate limits, or maximum text length, so the disclosure is partial.

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?

Tight, front-loaded fragment that leads with purpose and return type, then cost, then options, with zero filler. The unresolved '? cr' placeholders are the only blemish, making it slightly less actionable than it looks.

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 5-parameter generation tool with no output schema, the description correctly covers the return artifact (MP3) and cost model, so an agent knows what comes back. It still omits practical limits — maximum text length, exact credit price, and failure modes — and the unknown credit figures undercut the cost warning it does provide.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema for the `voice` parameter by enumerating accepted forms (roster id, cloned voice id, or char:<id> for character speech) which the schema only calls 'Voice id (default aria)'. It also ties the two models to their credit cost framing, though the values are unknown.

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 (text-to-speech generation) and the output artifact (MP3 audio), which cleanly separates it from generate_image, generate_music and generate_video in the sibling list. An agent can identify the tool's job 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?

The description names available models and voice sources and routes the agent to list_voices for roster ids, which is a useful pointer. However, it never states when this tool is preferred over alternatives or any preconditions (e.g., credit balance, text length limits), leaving usage largely 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?

With no annotations, the description carries the full burden and does so well: it discloses async execution, 1–5 min latency, credit cost per clip with exact per-model prices, and plan-tier gating (creator+/hobby+). It stops short of covering failure behavior, idempotency, or whether the render is cancellable, which are meaningful gaps for a credit-spending mutation.

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 operation, latency, and cost profile, then the routing instruction. The per-model cost/tier enumeration is long but each entry earns its place because model selection is gated on price and plan; it could be tightened into a table 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?

For an 8-param, no-output-schema tool, the description covers the essentials: what it does, how long it takes, what it costs, and how to retrieve the result via get_video_status using the returned id. Minor omissions (cancellation, partial-failure handling) are tolerable given the absence of annotations.

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 decision value beyond the schema's vague 'Some models need a paid plan' by mapping each of the 16 enum values to a credit price and minimum plan tier. This directly informs the `model` parameter choice in a way the schema 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?

Opens with a concrete verb+resource ('Start a video render') and immediately qualifies the operation as async with a 1–5 min duration. It is trivially distinguishable from siblings like generate_image, generate_music, and generate_speech.

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 states the follow-up path: 'If still processing when this returns, poll get_video_status with the returned id,' which names the sibling and the condition that selects it. It does not, however, contrast this tool against generate_image/generate_music for ambiguous 'make me media' requests, leaving that inference to 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?

readOnlyHint already covers the safety profile. The description adds two pieces of real behavioral context beyond annotations: the call is free, and the result is scoped to "the key in use." It does not disclose auth failures, rate limits, or whether a missing/invalid key errors out.

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 fragments, front-loaded with the cost fact and then the payload. Nothing is wasted, though the telegraphic "Free." fragment reads as a label rather than a sentence and could carry slightly more structure.

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 does the job of listing what comes back (credit balance, plan, workspace). For a zero-parameter read tool this is nearly complete, missing only the detail of returned field shapes or the behavior when the key is invalid.

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

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

The tool takes zero parameters, so the schema imposes no semantic burden and the baseline of 4 applies. Nothing in the description is needed to explain parameter usage.

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 specific resource and the exact data returned: credit balance, plan, and workspace. It is unambiguous against siblings like list_models or get_image_status, though it never explicitly says it takes no parameters or why it exists as a distinct lookup.

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?

"Free" implies the operation costs no credits, which is a lightweight usage signal (call it before expensive generation to check balance), but it never states when to call this versus other tools or what preconditions exist for the key in use.

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

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

Annotations only declare readOnlyHint=true; the description adds real behavioral context beyond that: the call is free, rendered links are signed and expire in 30 minutes, and there is a post awaiting a human in the studio (a human-in-the-loop condition). This is useful non-obvious disclosure, though the signed-link and pending-post implications could be spelled out more clearly.

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 leads with 'Free' and then lists the response contents compactly. The em-dash list is dense and largely earns its place, though the poetic framing ('the words it wrote', 'waiting for the person in the studio') costs some precision.

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 must convey return contents, and it does: step statuses, generated text, signed render links, spend, and a pending post. It is complete enough to set expectations for a read-only status tool, though the exact shape of the payload remains only loosely described.

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 (flow, run) are already documented in the schema. The description adds no syntax, format, or constraint details about flow/run beyond the fact that a run belongs to a flow. Baseline 3 is appropriate when the schema carries the parameter burden.

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 (a flow run's status) and enumerates what the response covers: step statuses, written words, rendered links, spend, and a pending post. This distinguishes it from the media-status siblings (get_image_status, get_music_status, get_video_status), though the phrasing is stylized enough that the core verb 'get/report status' must be inferred.

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?

No explicit when-to-use guidance and no routing to alternatives. An agent could infer this is used after run_flow to poll a run, but the description never says so, nor does it distinguish this from list_flows. 'Free' hints at cost but is not usage 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 only declare readOnlyHint=true; the description goes well beyond that by disclosing cost ('Free'), the success return ('Returns the picture once it succeeds'), and failure economics ('failed renders refund themselves') — non-obvious billing and retry semantics an agent cannot infer.

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 front-loaded sentence with the core action first, then the gating condition, cost, return behavior and failure handling. No filler; every clause carries 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 supplies the missing return contract ('returns the picture once it succeeds') plus the failure outcome, which is exactly what an agent needs to poll and terminate 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% and the single id parameter is already documented as the job id from generate_image. The description's 'by id' restates the schema rather than adding format or constraint detail, 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 ('Poll an image job by id') and immediately scopes it against the sibling tools get_video_status/get_music_status by naming the image job domain. An agent can select it without opening the schema.

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

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

Explicitly gives the triggering condition ('only needed when generate_image handed back a job id'), naming the sibling that produces the input. This tells the agent both when to use it and when not to bother.

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, so the safety profile is covered, but the description adds genuinely useful behavior: polling is free, the MP3 plus link is returned only on success, and failed jobs refund themselves. That billing and terminal-state behavior is not derivable from annotations or schema. Minor ambiguity remains around 'Free' vs. self-refunding failures.

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

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

Three short sentences with zero filler; the core action, the cost note, and the outcome states are front-loaded in that order. Every clause carries 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 correctly carries the return-value burden by stating that the MP3 and its link come back on success. The main omission is timing behavior (poll cadence, expected latency, link expiry) for an inherently async status tool, but nothing essential for calling it correctly is missing.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema as 'the job id returned by generate_music'. The description only echoes 'by id', adding no format, sourcing, or lifecycle detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Poll a song job by id'), and the required 'id' is tied back to generate_music in the schema, which lets an agent place it correctly in the async generate-then-poll workflow. It doesn't explicitly contrast itself with the parallel get_image_status/get_video_status siblings, but the scope is 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?

Usage is implied rather than stated: 'Poll a song job by id' suggests calling after generate_music and repeating until completion, but the description never says to poll repeatedly, how long to wait, or that this is the only way to retrieve the result. No explicit when-not or alternative is given.

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?

With no annotations, the description carries the full behavioral burden and discloses useful traits: it is free, returns the clip URL on success, and failed renders refund themselves. It does not mention authentication, rate limits, or whether repeated polling is safe, but it covers key cost and outcome behavior.

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 tightly written sentences with the core purpose front-loaded. 'Free' is a terse but valuable cost signal, and the success/failure behavior is stated compactly without waste.

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

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

For a simple one-parameter polling tool with no annotations and no output schema, the description covers purpose, cost, success return, and failure refund. It could better explain the pending state or response shape, but the word 'Poll' implies repeated calls and the core behavior is clear.

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 already explains that the id is 'returned by generate_video.' The description adds only 'by id,' so it does not meaningfully extend parameter semantics beyond the schema. 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?

States a specific verb+resource: 'Poll an async video job by id.' The resource 'video job' clearly distinguishes it from sibling status tools like get_image_status and get_music_status. An agent can identify its function 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?

The word 'Poll' implies repeated calls and the schema parameter description ties the id to generate_video, giving implied usage context. However, the description does not explicitly state when to use this tool versus alternatives or when not to use it, leaving the agent to infer the workflow.

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?

readOnlyHint=true already establishes the safe-read profile. The description adds real value beyond annotations by disclosing that calls are free (no cost) and that identifiers are formatted char:<id>, but it says nothing about the return shape, pagination, or how many characters are typical.

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 with the cost hint front-loaded. The second sentence is dense and slightly elliptical ("mention their photos as reference images"), but 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, the description is the only source for what comes back, and it only hints at ids (char:<id>) and photos without describing the returned fields or structure. Adequate for a trivial no-arg read, but the result contract is left partly 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?

Zero parameters, so there is nothing to disambiguate; the baseline for an empty schema is 4. The description does not need to compensate for any undocumented 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?

"The account's cast" identifies the resource being listed (the account's characters/voice assets), and the mention of char:<id> ties it concretely to generate_speech. It stops short of an explicit verb like "list/returns" and leans on metaphor ("cast"), but an agent can distinguish it from list_flows/list_voices/list_models by the speech/photo references.

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 downstream context for using results: reference char:<id> in generate_speech's voice, or use their photos as reference images. That effectively tells the agent when this tool is needed (before speech generation or image reference use), though it names no explicit "use this instead of X" alternative.

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

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

With readOnlyHint=true already declaring a safe read, the description adds context the annotation does not: it costs nothing, and it enumerates the exact payload fields (id, name, trigger type, steps, published state, last run), which substitutes for the absent output schema. No pagination or result-count behavior is disclosed, keeping it below 5.

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

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

One sentence, front-loaded with the cost signal and the resource, with zero filler. The parenthetical trigger list and field enumeration are dense but each item earns its place by describing return contents.

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 read tool with no output schema, the description effectively documents the return shape and the free-cost behavior, which is what an agent needs to call it. It stops short of noting pagination or how many flows come back.

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 indicates no filtering input is required. It cannot add parameter meaning because none exist, and 'the person's Flows' usefully implies scoping is implicit rather than passed in.

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 person's Flows), and defines what a Flow is ('automations built in the eroq studio'), which separates it from create_flow, edit_flow, run_flow and get_flow_run. An agent can identify this as the enumeration tool 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?

The 'Free.' prefix signals this call has no cost, which implicitly favors it over paid siblings, but there is no explicit when-to-use guidance or named alternative (e.g. get_flow_run for a single run). Usage is implied rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe, side-effect-free read. The description adds genuinely useful context beyond that — the call is free and video entries carry plan-gating info — but says nothing about result size, ordering, or whether it's cached.

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 90-character sentence with the cost signal front-loaded and no filler. Every clause earns its place by naming the returned attributes.

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 list the key fields (kind, credit price, plan unlock). It stops short of describing ordering or entry count, but for a zero-param catalogue lookup it is close to sufficient.

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 clarify beyond what the schema provides; baseline 4 applies. The stated return fields are a bonus, not a param explanation.

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

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

The description names a concrete resource (models) and enumerates what each entry contains: kind, credit price, and plan-gated video access. That cleanly separates it from the other list_* siblings (characters, flows, voices) without naming them 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?

'Free' implies this is the cost-checking lookup to call before spending credits on generate_* tools, but the description never states when to reach for it versus list_flows/list_voices or confirms there are no filters to apply. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely new context: 'Free' (cost), and the fact that results include account-scoped cloned voices and not just a generic roster. No pagination or return-shape detail, but the bar is lower given 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?

Extremely tight and front-loaded: cost note first, then scope, then the integration hint. Every clause carries distinct information with no filler.

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

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

For a no-parameter list tool with annotations covering safety and no output schema, the description supplies enough to call it correctly, and the 'ids usable as...' clause partially anticipates the return shape. It could say a bit more about what the returned entries look like, but nothing critical is missing.

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

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

Zero parameters, so the baseline is 4; schema coverage is 100% and there is nothing further for the description to clarify.

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 resource concretely ('the speech roster plus the account's cloned voices'), which separates it from sibling lists like list_characters, list_flows, and list_models. The verb is only implied via the tool name, but the scope is 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?

It clearly states the downstream use case — the ids are 'usable as generate_speech's voice' — which tells an agent when this tool matters. It stops short of any when-not guidance or comparison to other listing tools.

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 single readOnlyHint annotation: states it costs no credits, that defaults come from the latest Library items, that the output is a link whose edit is laid out in the browser and is editable and exportable as MP4. The readOnlyHint=true is consistent with the claim that the server only answers a link and the studio does the work, so no contradiction.

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 key facts (free, no credits, what it does, what it returns) before the style list, so the agent gets the essentials first. The style parentheticals are long and slightly chatty ('like a TikTok edit'), but each earns its place by disambiguating the enum values.

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: it explains the tool answers a link, that the studio reads beats in-browser and opens an editable timeline, and that the result exports as MP4. Defaults for clips, count, and song are all covered.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: 'clips' order and the fact that ids override the latest-items default, 'song' as Storage name or id, and a behavioral characterization of each style value (aura, phonk, villain, velocity) that the schema only labels as 'The edit style.' That materially improves style selection.

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 verb and resource: cutting the person's clips and pictures on a song's beats in a chosen style, returning an editable timeline link. This is clearly distinguishable from siblings like generate_video or edit_flow, which do not do beat-synced montage. The style enumeration further pins down what the tool 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?

Gives clear context for use (beat-synced TikTok-style edit, free/no credits) and states the input conditions: latest Library clips unless creation ids are given, song from Storage by name, 120 BPM grid fallback. It stops short of explicitly saying when to prefer it over edit_flow or generate_video, so it lacks exclusion 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?

With no annotations, the description carries the full burden and does so well: it discloses the asynchronous contract ('returns the run id at once — the flow keeps going on eroq's servers'), the billing implication ('each render the flow makes is charged like any generation'), and the plan requirement. This is exactly the behavioral context an agent needs before invoking.

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 action, then prerequisites, parameter guidance, cost, and return semantics in tight succession. No sentence is filler; each carries a distinct fact.

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 explaining the return value (a run id, returned immediately) and how to track the run via get_flow_run. Combined with cost and plan notes, nothing essential for a correct call is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including that prompt and image are conditional ('when it asks for a prompt'). The description largely restates this with 'and/or', adding little beyond the structured fields, 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 ('Run one of the person's Flows now') and scopes it by naming the plan tier. It also distinguishes itself from the surrounding siblings by pointing to get_flow_run for follow-up and implying list_flows for id lookup.

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: name the flow by id or exact name, and supply prompt/image only when the flow requires them, plus a prerequisite (Studio plan and up). It names get_flow_run as the follow-up tool, but does not explicitly state when to prefer this over create_flow/edit_flow.

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