Doseedo Film Score: spot a video, play your score on AI instruments, mix it to picture

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

The annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds useful behavioral context: the call consumes no credits and the monthly pool is shared by generation and DAW conversions. That budget-consumption detail is valuable beyond the annotations, though return formatting and auth requirements are not described.

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, with purpose and returned information front-loaded. The read-only/no-consumption caveat and usage recommendation each earn their 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 a zero-parameter tool with full annotation coverage and no output schema, the description is complete enough to call correctly. It states what the tool reports, that it is read-only, that it consumes nothing, and when to use it.

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?

There are zero parameters, so the baseline is 4. The description appropriately uses the space to explain account fields and credit semantics rather than parameter behavior.

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: checking the connected doseedo account. It enumerates the concrete data returned: plan tier, monthly credit pool, extra-usage credits, and storage. It also distinguishes this diagnostic tool from the many action-oriented sibling tools.

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 explicitly says to use the tool before starting expensive work to confirm budget, which gives clear usage context. It does not name an alternative or a when-not-to-use condition, but the guidance is sufficient for a zero-parameter read-only account check.

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?

The description provides rich behavioral context beyond the annotations, detailing the synchronous nature of the operation, the time and CPU cost, and the lifecycle management of the job, including confirmation instructions and cancellation policy.

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 quite dense and long, sacrificing brevity for extremely high information density. However, the information is logically structured, though its overall length makes it less concise than ideal.

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?

Despite lacking a formal output schema, the description is highly complete. It explicitly details the expected data fields to check in the results (e.g., 'chords[].chord / sonorities[].anchor') and clearly outlines the job completion flow.

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?

While the schema is 100% covered, the description adds critical domain expertise that the schema lacks. It clarifies the specific functional difference between the 'midi' mode (being chord-detection-free) and the 'chord' mode (output density), as well as how to correctly utilize the optional 'idempotency_key'.

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 immediately identifies the tool's purpose: analyzing MIDI harmony. It clearly distinguishes its capabilities across two operational modes: 'midi' (chord-detection-free sonorities) and 'chord' (chord symbols).

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 tool specifies how it must be invoked by accepting either a detailed 'notes[]' array (or a 'midi_url'). It provides critical operational constraints regarding timing ('Synchronous (~2–10 s)') and resource allocation ('CPU, no credits').

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 past the annotations (destructiveHint=true, idempotentHint=true) by disclosing exactly what is destroyed, what is refunded, and which kinds cannot be stopped plane-side. The refund semantics — credits spent vs. refunded, separation charges retained — are the kind of consequence detail annotations cannot convey.

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

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

Front-loaded with the core action, then a structured kind-by-kind breakdown with consistent labels and semicolons. It is long, but nearly every clause carries distinct behavioral information; the density is justified even if a summary line would aid scanning.

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 mutation tool with no output schema, the description covers eligibility, side effects, refund behavior, and terminal-state errors. Nothing an agent needs to call it correctly or predict consequences 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% for the single job_id parameter, so the baseline is adequate. The description adds no format or sourcing detail beyond the schema's own note, though the per-kind taxonomy implicitly tells the agent which submit tools produce cancellable job_ids.

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 ("Cancel a queued or running job") and immediately scopes which job states are eligible. It goes further by enumerating job kinds, which lets an agent distinguish this from submission siblings like doseedo_generate_music or doseedo_bounce_session 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?

Makes clear the tool applies to queued or running jobs and explains per-kind outcomes, plus notes that finished synchronous analyses return 409 already_terminal — effectively telling the agent when not to call it. It stops short of naming alternatives explicitly (e.g., doseedo_list_jobs to obtain job_id), though the schema description covers that pointer.

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 real context beyond annotations: synchronous ~3–15 s, CPU-bound, no credits, cancel not applicable because the response is the result, and the underlying method (basic-pitch) with its failure modes (dense chords, fast runs). Annotations already cover the read/write and open-world profile, so this is above bar, though it could state auth or size constraints more explicitly.

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 imperative and the payoff, with latency, cost, and method caveats deferred to the end. It is dense and long for a single paragraph, but nearly every clause 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?

With no output schema, the description fully compensates by describing the return payload (metrics, first missed notes with beats, timing error, loudness, verdict with reasons). Input alternatives, runtime, cost, and accuracy limits are all covered, leaving no material gap for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3; the description earns extra by clarifying the input modes — notes[]+bpm/tempo_map versus midi_url — and that instrument names switch to onset-only matching. Defaults like onset_tolerance_ms and time_signature remain schema-only, which is fine given full coverage.

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 specific verb and resource ('MEASURE a take') and immediately enumerates what it returns (recall/precision/f1, octave errors, timing error, LUFS, verdict). The input requirements are stated inline, so an agent can tell this apart from siblings like doseedo_transcribe or doseedo_analyze_midi 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 says when to use it and offers an alternative: doseedo_render_midi results already carry takes[].check, so checking a rendered part is redundant. It also gives the working caveat — 'use it as a screen, and listen to anything marked check' — which tells the agent how to act on the output.

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

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

Annotations already cover read-only, idempotent and non-destructive behavior, so the description's added value is the single-shot polling model and the fact that large results are truncated to deciding fields unless parts is given. That truncation detail is genuinely useful context an agent cannot get from the annotations. It stops short of describing status values or behavior on unknown/expired jobs.

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 key facts (single check, status and result, brief default) are front-loaded and there is little waste. The final parts sentence is a dense run-on with awkward punctuation, which slightly hurts readability.

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 reasonably well: status, file URLs / notes, and the truncation/expansion model are all covered. Missing are error or still-pending cases, which an agent polling a job would want.

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 goes beyond the schema by explaining the default 'brief' result shape and exactly what 'in full' means for different part types (a render_score part's every receipt, a mix part's strip, rides and loudness). That is real added meaning for choosing the parts parameter.

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

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

States a specific verb and resource ('Check an async doseedo task once') and describes the outcome (status plus result when finished), which is far more than the title. It distinguishes itself only implicitly from doseedo_wait_task via the word 'once'; the sibling is never named.

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 'once' implies a poll-again-later pattern versus blocking, but the description never says when to use this instead of doseedo_wait_task or doseedo_list_jobs, nor what to do if the job is still running. 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?

The description provides extremely high behavioral detail that is not in the schema or annotations, specifically regarding the asynchronous workflow, the use of `doseedo_wait_task`, URL handling (pre-signed, no auth), and a nuanced cancellation policy based on GPU state.

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?

While extensive, the detail is perfectly justified by the tool's complexity (handling asynchronous state, cancellation, and varied resource types). The information is front-loaded with high-value context.

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?

Given the need to manage an asynchronous job lifecycle, the description is exceptionally complete, covering request, waiting, retrieval, and termination in detail.

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?

Although schema coverage is 100%, the description adds vital semantic rules regarding parameter interaction, such as how omitting 'kind' defaults to prompt content, and the functional consequence of putting tempo words in a hit's prompt.

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 tool clearly states its purpose as generating sound effects (SFX) and Foley. It explicitly distinguishes itself from sibling tools by stating it is the wrong tool for music, thereby defining its operational scope precisely.

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 provides immediate, practical guidance on usage with extensive examples (impact, whooshes, UI blips). Crucially, it provides 'when not to use' guidance by referring the user to specific sibling tools for musical content.

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 the safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=true); the description adds real behavioral context beyond that — the PUT-with-raw-bytes protocol, the ≤2 GB film limit, universal format acceptance on every plan, and the plan-tier caveat that lossless WAV/AIFF/FLAC is not retained in sessions below Pro+. It omits presigned-URL expiry/reuse semantics, which matters for a time-limited credential.

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-loading is good — purpose and return values come first — but the remainder is a single dense paragraph mixing protocol, film handling, plan tiers, format lists, and a local-file alternative. For a two-parameter tool this is over-packed and would read better split into short labeled sections.

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 (upload_url + audio_key, plus the exact PUT invocation). Combined with format, size, and plan caveats, an agent has enough to call it correctly; only URL lifetime and whether repeat calls return the same key 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 coverage is 100% and already documents filename-with-extension and content_type inference from extension. The description reinforces content_type by showing it used in the PUT header and enumerates the accepted formats, but adds no parameter-level detail the schema lacks — baseline 3.

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 specific verb+resource: 'Get a presigned upload for your own audio file', and states exactly what comes back (upload_url, audio_key). It never contrasts itself with the similarly named sibling doseedo_get_project_upload_url, so an agent must infer which upload-URL tool applies to which artifact.

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 the returned key to the four consuming tools plus doseedo_add_audio_to_session and video_key for doseedo_spot_video / doseedo_score_to_picture. It also gives a clear when-NOT-to-use case: local samples/regions 'need NO upload' and should instead use load_quick_sampler_sample / attach_audio / set_track_clips with place_local_files.

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 readOnly/idempotent/non-destructive, and the description adds real context on top: 'free, no key needed', that no args returns the whole catalog, and exactly what each entry contains (render call, timbre preset, range, chord capability, presets, demo). That is genuine behavioral disclosure beyond the structured fields.

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 core purpose and the filtering modes in one dense paragraph where every clause carries information. It is long and parenthetical-heavy, but there is no filler sentence to remove without losing catalog semantics.

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 describing return contents — and it does, enumerating call, range, chord support, presets, and demo per entry. An agent has everything needed to call it and interpret 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?

Despite 100% schema coverage, the description adds meaning the schema doesn't: illustrative queries ('warm low brass'), that query results are ranked best-first, that pitches filters to instruments whose range holds every pitch, and that id returns one instrument in full with all presets. This meaningfully upgrades parameter interpretation.

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 — the full instrument catalog — and defines scope precisely: every instrument doseedo can render notes on, broken down by families and with concrete exotic examples. An agent can immediately distinguish it from siblings like doseedo_list_plugins or doseedo_train_instrument.

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 tells the agent to 'read it before writing a part' and ties it to the downstream tool doseedo_render_midi, which is strong when-to-use guidance. There is no explicit when-not or named alternative, but for a catalog tool the routing is essentially unambiguous.

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

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

Beyond the readOnlyHint annotation it adds ordering ('newest first') and the key caveat that rows only name artifacts while links must be re-fetched via check_task. 'Read-only' merely restates the annotation, and pagination/limit behavior isn't discussed, so it stops short of full behavioral disclosure.

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 action and scope, then use cases, then the artifact/link caveat. The parenthetical kind list is dense but earns its place by mapping casual names to the tool's domain; every sentence 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 covers the essential return shape (rows with artifact names, newest-first ordering) and points to the sibling for full results. It omits any mention of cursor-based paging or the next_cursor field an agent needs to iterate, which is a minor but real 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 80% and the schema itself documents kind aliases, limit bounds, the before cursor, and the page-scoped session_id filter. The description only indirectly references the kind parameter through its list of job types, adding no format or boundary 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?

Names the specific verb and resource ('List the jobs this account submitted') and enumerates the job kinds covered, so an agent immediately knows the scope. It also distinguishes itself from doseedo_check_task by describing that as the full-result 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?

Explicitly states three concrete situations to call it: finding an earlier result, checking what is still running, and resuming after a lost connection. It also routes to the alternative ('doseedo_check_task {job_id} returns the full result with fresh links') for the case where a fresh link is needed.

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?

It discloses behavior well beyond the annotations: output includes WAV and mixgraph, edits through mix_job render as written with safety rails and no credits, and async jobs take roughly 15–90 s. It also gives unusually specific cancellation semantics — no stop for a running mix, credits spent, output discarded, only queued jobs refunded — without contradicting readOnlyHint=false or destructiveHint=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?

The purpose and primary workflow are front-loaded, and the length is largely justified by the tool's 15 parameters and many edit pathways. It is dense and paragraph-like rather than sectioned, so scanability suffers slightly, but most sentences carry actionable information rather than filler.

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

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

With no output schema, the description still explains the returned artifacts (WAV and mixgraph), key report fields such as report.strips.<part>.active_lufs, async job handling, and cancellation limitations. Given the complexity and rich input schema, an agent has enough context to invoke and follow up correctly.

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

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

Schema coverage is 100%, so the schema already carries most parameter definitions. The description still adds cross-parameter workflow meaning for from_job, stems, mixgraph, and mix_job, and supplies the long style id list that the schema only partially exemplifies, though many individual parameter details remain schema-led.

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 opening states a specific verb and resource — mixing and mastering stems instead of summing them — and enumerates the concrete processing applied. It also names related tools and input modes, so an agent can distinguish this from rendering, stem separation, or session creation.

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 gives explicit entry paths: use from_job after doseedo_render_score, or pass stems directly; then edit the returned mixgraph and call again with mix_job or with the same from_job/stems. It also routes the follow-on step to doseedo_session_from_stems and explains the async wait path with doseedo_wait_task.

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 readOnly/idempotent/non-destructive, and the description reinforces this with 'Spends nothing' and adds genuinely new context: the estimate follows the planes' price table while 'the gate is authoritative and a refusal names the exact price'. This warns the agent that the quote and the actual charge can diverge — useful, non-obvious behavior. It doesn't say what the response object looks like beyond `refused`.

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 benefit and the 'spends nothing' guarantee are well front-loaded, but the description then dumps the full 22-item enum inline, duplicating the schema and bloating an otherwise efficient statement. The price-rule clauses are valuable but delivered as a dense run-on.

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 still conveys the return shape well enough: a credit estimate, an affordability answer, and a `refused` field indicating when the job would be rejected. For a two-parameter read-only tool this is close to sufficient, though the exact response fields are only sketched.

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 earns extra by explaining that `args` should mirror the job tool's arguments ('only the price-relevant ones matter') and by giving non-obvious pricing semantics — takes are free while voices cost one batch per ~6, and render_score parts are planned exactly as the job plans them. The detail is uneven, focused on only two of the 22 jobs.

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 ('Estimate what a job will cost in credits') plus the pre-condition timing ('BEFORE submitting it') and the affordability check. An agent can instantly separate this from doseedo_generate_music or any other job tool, which actually spend credits.

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 frames the use case as pre-flight pricing before invoking the job tool and reassures 'Spends nothing', which is the key decision input. It does not name a hard alternative (e.g. doseedo_account for balance) or state when-not to call it, so it falls short of a 5.

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 readOnly/idempotent/non-destructive, and the description confirms read-only. Beyond that it discloses the payload of each recipe — inputs, ordered tool calls, outputs, credit/time estimate, and how to VERIFY success from the response — which is genuine behavioral context an agent needs before trusting the guide.

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 a clear scope statement, but the recipe enumeration is a single very long em-dash sentence that becomes a wall of text. Every clause is informative, yet the structure could be tightened.

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

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

No output schema exists, so the description carries the burden of explaining return content — and it does, listing inputs, ordered tool calls, outputs, estimates, and verification guidance. Complete for a one-parameter read-only reference 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 100% and already documents omitting name to list all. The description adds value by naming the index concept and tying recipes to a use_when selector, plus mentioning aliases implicitly in the recipe list — marginal but real beyond 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?

Names a specific resource — a catalog of named multi-step pipelines — and enumerates them (stems, session, cover, transcribe, render-midi, timbre-transfer, analyze-song, etc.), so the agent immediately knows this is a reference/guide tool rather than an action tool. It is cleanly distinguished from the many sibling action tools that actually perform those steps.

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 two invocation modes: no name returns the index (to pick by use_when), a name returns the full recipe. What is missing is guidance on when to consult this versus calling sibling tools directly, though the recipe content description implies it should be read before assembling a multi-step 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?

Beyond the annotations, it discloses async job behavior (~1–3 min via doseedo_wait_task), best-first take ordering, pre-signed 24-hour result URLs, note-imperfection caveats, cancellation/refund semantics, and drum-model hit-dropping behavior. These are substantive operational details an agent needs before invoking the tool.

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?

It is front-loaded with purpose and core inputs, then branches into drums, sound, and cancellation, and nearly every sentence carries operational information. However, the description is extremely dense and long, with many parenthetical clauses, making it harder to scan than it could be for a 32-parameter tool.

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?

Given the tool's complexity, 32 parameters, no output schema, and open-world behavior, the description is unusually complete: it covers input selection, required fields, async lifecycle, result shape, take-quality caveats, drum/synth routing, timbre options, and cancellation semantics. An agent has enough context to invoke it correctly without additional documentation.

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?

Although schema coverage is already 100%, the description adds high-value semantics: it explains the notes/midi_url/session-track alternatives, how instrument ids are sourced from doseedo_instruments, the purpose of voice_split, drum_engine, timbre transfer, LoRA application, and revise-region behavior beyond the schema text.

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: render MIDI notes through an AI instrument model and return audio takes. It explicitly distinguishes itself from doseedo_generate_music by noting that generate_music takes no notes or key, so an agent can choose between them without inspecting schemas.

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 a clear triggering scenario ('I wrote the part, now play it'), names the alternative for note-less generation, and points to doseedo_analyze_midi as a free harmony check first. It also explains the three mutually exclusive input modes (notes[], midi_url, or session_id + track_id) and when to use each.

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 async job behavior, expected wait time (1–4 min), cancellation/refund rules, orchestral limits (≤32 lines, ≤96 player rows, ≤600 s), one automatic re-roll for failed parts, and output fields for fit/coverage/tuning. These are operationally important facts not captured by readOnly/openWorld/destructive hints.

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

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

The purpose is front-loaded, but the description is extremely dense, using all-caps phrases, parentheticals, symbols, and repeated references to doseedo_instruments that make it harder to parse. Much of the length is justified for a 14-parameter render tool, but the delivery is not tightly concise.

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 complex, 14-parameter async rendering tool with no output schema, the description is highly complete: it explains input modes, orchestration/section semantics, timing, output fields (url, fit, mix_url), next steps, wait behavior, and cancellation consequences. An agent has enough context to invoke and follow up 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 already 100%, so the schema carries the basic parameter meanings. The description adds useful semantics beyond the schema: file parts are matched by name then GM program, instruments{} can override by part name/index, and players converts a line into a section stem.

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: rendering a WHOLE ARRANGEMENT as stems plus mix from parts[], MIDI, or MusicXML. It distinguishes this from doseedo_render_midi by reserving synth/electronic parts and tightly timed drums for that sibling, so an agent can select it without opening schemas.

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 explicitly names the alternative doseedo_render_midi and the condition that selects it: synth/electronic parts and drums where every hit must land. It also states the three valid input modes and gives concrete examples (film cue, string quartet, big-band chart), leaving little 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?

Goes well past the annotations: no re-encode ('muxes it onto the picture untouched'), CPU-only with no credits, async job semantics, up to 25 min per call, and a candid warning that a running delivery cannot be stopped and discards output on cancel. It also enumerates what the returned report measures, which is valuable for a job with 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?

The core purpose is front-loaded, but the description is a dense wall of parentheticals covering ducking, loudness, returns, tracks syntax, limits, and cancel policy in one block. For a 10-parameter tool this length earns its place, though it could be broken into paragraphs for scanability.

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 complex, nested-schema, no-output-schema tool, it covers what is produced (scored video, printmaster WAV, M&E stem, measurement report), the async continuation path, and the operational limits. Nothing needed to invoke 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 already 100%, but the description still adds real meaning: audio_url can be a doseedo_mix mix_url, the loudness preset names map to specific LUFS values, production_audio 'drop' is illustrated with a temp-score example, and the tracks array shape with the ≤64 cap is spelled out. It stops short of explaining every duck tuning knob, but the schema does that.

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 up front ('SCORE TO PICTURE: the last step of scoring a film'), then lists the concrete operations: laying cues at SMPTE timecode, ducking, loudness normalisation, and muxing onto the picture. It clearly distinguishes itself from doseedo_mix (which produces the cue) and doseedo_spot_video (which uploads the picture).

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?

Positions the tool in a workflow ('the last step'), gives the alternative paths (keep vs drop production audio, with the temp-score replacement example), tells how to supply dialogue instead of VAD detection, and names the follow-up tool (doseedo_wait_task). It also states the 25-minute/reel limit and the cancellation/refund rules so there are no surprises.

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 annotations, it discloses async timing (~30–90 s), the pre-signed zip download pattern with curl, 24-hour expiry, cancellation limitations, credit-spend behavior, and refund conditions. It also clarifies that mixgraph EQ, compression, reverb, and rides are not written into the project.

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 dense but front-loaded, starting with the core build action and deliverable before moving into input modes, async behavior, and cancellation caveats. Despite its length, every sentence carries operational information relevant to invoking the tool correctly.

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?

Given 11 parameters, nested stem/MIDI objects, no output schema, and asynchronous execution, the description provides the missing operational context: how to use upstream job IDs, what the output is, how to retrieve it, and what cancellation does. Nothing essential for correct invocation appears 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 schema already documents all parameters. The description adds useful cross-parameter semantics, especially that from_job supplies stems, MIDI, and tempo without other input, that result links work as-is, and that mix_job causes tracks to inherit level/pan with a muted reference mix.

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 action and deliverable: build a native DAW project from stems, with each stem on its own track, optional MIDI tracks, and target formats Logic Pro or Ableton Live. It distinguishes the tool from sibling creation/import/convert tools by emphasizing stems as the input and a zipped DAW session as the output.

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 explicitly names upstream alternatives and when to use them: after doseedo_render_score with from_job, after any renders or separations with stems, or after doseedo_mix with mix_job. It also explains the async follow-up flow via doseedo_wait_task, making the intended invocation path 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?

Goes well beyond the annotations: async job_id → doseedo_wait_task with an expected runtime, CPU/no-credit cost, hard input limits (≤2 GB, ≤3 h), and a precise disclosure that a running spotting pass cannot be stopped and credits are spent even though the job ends canceled. The annotations (readOnlyHint=false, destructiveHint=false) don't cover any of this, so the description carries real weight.

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 verb and output, and nearly every clause carries operational information. It is dense and longer than typical, with input limits and pipeline steps packed into a long run-on, which costs a point but not much value 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 still documents the return shape thoroughly (cue ids, SMPTE start/end, emotion, energy, tension arc, ranked hit points, suggested bpm, tempo_map_input handoff). Combined with the async flow and cost caveats, an agent has everything needed to call and follow up correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds file-size/duration constraints and explains coverage's intent ('raise for wall-to-wall scoring, lower for a dialogue drama') plus how video_key/video_url relate. Most other params (reel, keyframes, cut_threshold) are only restated, keeping it at 4.

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+resource+output: 'a video in, the music editor's cue sheet out — the first step of scoring to picture'. An agent can immediately distinguish this from doseedo_analyze_song or doseedo_score_to_picture, and the description enumerates what the output cue sheet contains.

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?

Strong routing context: it positions itself as the first step and chains 'Next: doseedo_tempo_map per cue → ... → doseedo_score_to_picture'. It also warns on cancellation semantics. It stops short of explicitly saying when NOT to use it (e.g. audio-only, MIDI sources), so 4 rather than 5.

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 non-destructive behavior, but the description adds valuable context beyond them: 'Pure math: free, instant, no key needed,' supported timecode frame rates, and the exact shape of the returned tempo map and hit placements. This tells the agent about cost, speed, auth requirements, and output semantics that structured fields alone do not provide.

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 dense but front-loaded: the core action comes first, followed by output-usage guidance and timecode support. Every sentence contributes useful information, though the middle sentence is packed with several ideas at once.

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 fully specifies what is returned: tempo_map [{beat, bpm}] and hits[] with beat, bar, and beat-in-bar placement. It also covers input flexibility, timecode handling, and downstream tool integration, leaving no material gap for an agent calling this 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 description coverage is 100%, so the schema already documents all eight parameters. The description still adds meaning by explaining how hits can be bare numbers, objects with time_s or timecode, per-hit 'land' overrides, and how the tempo map stays near bpm but inside bpm_range. This is more than schema repetition and helps an agent assemble correct 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 description states a specific verb and resource ('turn HIT POINTS into a TEMPO MAP') and explicitly distinguishes the tool's role from siblings by naming the downstream consumers (doseedo_render_midi, doseedo_render_score, doseedo_session_from_stems). An agent can tell this is a scoring-to-picture tempo-mapping utility, not a generic renderer or beat-grid analyzer.

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 establishes the use case ('Scoring to picture') and what inputs to supply, plus where the output goes next. It lacks explicit when-not-to-use guidance or direct comparison to alternatives like doseedo_beat_grid, but the context is strong enough for an agent to select it correctly.

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 past the annotations: discloses cost (20 credits), async job_id flow with ~1–2 min latency, owner-only rendering, transcription by default (skippable via notes), and unusually honest cancel semantics (no stop for a running training; it runs to completion and credits are spent, only plane-queued jobs are refunded). Annotations only say it mutates and is open-world, so this added context is substantial, though the 'queued at the plane' refund rule is slightly ambiguous in phrasing.

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: the core action and requirements come first, then result shape, then async/cancel details. A couple of the semicolon-chained asides (refund nuance, transcription note) are compressed to the point of near-illegibility, and the cancel paragraph is lower value than the setup guidance.

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 12-parameter async job tool with no output schema, the description covers the full lifecycle an agent needs: how to supply audio, how to choose instrument, default transcription, cost, result fields (lora_id, name, trained windows, loss first→last, and the ready-made `use` render args), waiting, and failure/refund behavior. 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 coverage is 100%, so the baseline is 3, but the description adds real meaning the schema cannot: that instrument selects the model voice the adapter trains on (shamisen trains as acoustic_guitar, whistle as flute) and that notes are auto-transcribed unless supplied. This is genuine interpretive value, not restatement.

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 — training a private LoRA adapter on the serving instrument model from uploaded audio — and immediately links the result to doseedo_render_midi, which clearly separates it from the rendering sibling. No ambiguity about what is produced (a lora_id usable in that sound).

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 input requirements (30 s–3 min, one solo dry instrument, up to 8 takes, first 3 min used, ≥8 s each), tells the agent how to pick the instrument (call doseedo_instruments, pick the nearest catalog voice, with concrete mappings), and routes to doseedo_list_jobs for prior runs and doseedo_wait_task for completion. This is when-to-use guidance with alternatives named.

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?

The annotations already declare readOnly/idempotent/non-destructive, so the description correctly spends its words on the long-poll mechanics the annotations can't convey: the hard 50 s server-side cap, the still_running flag contract, and what a finished job returns (output, pre-signed artifact links, note). It does not say what happens on job failure, cancellation, or timeout expiry with no result, which is the main behavioral gap.

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 and the cap, then the retry rule, then the return shape — a logical order with no filler sentences. The parenthetical duration lists for transcribe/render/audio_to_session are useful but dense enough that the sentence becomes slightly hard to scan.

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 contract itself and does so (output, artifacts, note, still_running), plus the polling cap and retry pattern — enough to invoke it correctly. Failure modes and the check_task alternative are the notable omissions for a tool in a family with cancel_job and check_task siblings.

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 restates timeout_seconds' 5–50 bound and the 'call it again' loop, and the schema itself documents the job_id-replaces-task_id+kind relationship; the description adds no new parameter meaning beyond that.

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 ('Wait for an async doseedo job to finish') plus the mechanism (server-side polling) and the return contract (result or latest status). It is clearly distinguishable from submit tools, but it never names the near-identical sibling doseedo_check_task, so the agent must infer the wait-vs-poll distinction itself.

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?

Strong guidance on the repeat-call pattern: 'If it returns still_running:true, call it again,' with eta_seconds from the submit reply as the budgeting heuristic and concrete duration examples. What is missing is the exclusion case — when to use doseedo_check_task instead, or how this interacts with doseedo_cancel_job.

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