Doseedo: Film Scoring, AI Instruments, Sound Effects & Stems

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?

Goes well beyond the annotations: it discloses that ingestion is server-side and that the return value is a sha256 handle, then shows exactly how that handle is consumed (attach_audio, or load_quick_sampler_sample with sample_path set to the sha). It also clarifies the 'no desktop needed' baking behavior into the exported .logicx, which is real behavioral context not implied by readOnlyHint=false or idempotentHint=true.

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 paragraph that opens with the action and the two input modes before diving into downstream usage. Heavily parenthesized and dense, but every clause carries information; minor tightening would help readability without losing content.

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

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

No output schema, and the description compensates by explaining that the result is a sha256 and how to use it, plus the ingestion model. Remaining gaps are small: whether session_id must reference an existing session, and whether re-ingesting the same file is deduplicated given idempotentHint=true.

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 75% and the schema itself describes audio_key, audio_url, and filename. The description adds the crucial mutual-exclusivity rule (audio_url OR audio_key) and the workflow that produces audio_key, which the schema does not state. session_id semantics remain unexplained in both places.

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

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

Specific verb + resource: 'Add an audio file to a session', immediately split into the two supported sources (public https URL vs. local file via audio_key). It also names the downstream consumers (attach_audio, load_quick_sampler_sample) so the agent understands where the result goes. It does not distinguish this from the near-identical sibling doseedo_audio_to_session, which an agent would have to guess between.

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?

Explicit conditional guidance: 'Give audio_url OR audio_key', with the local-file path spelled out as doseedo_get_upload_url → PUT bytes → pass audio_key. It also states pre-signed result URLs work as-is with no key. What's missing is any when-not guidance or a note on choosing this tool over its sibling.

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?

Annotations only carry the generic profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false, idempotentHint=false). The description adds genuinely non-derivable behavior: a 10-minute audio cap, synchronous execution with ~5–20 s latency and results in the submit response, no source separation so dense-mix chords are only a draft, and that cancellation does not apply because the job is already finished.

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 capability and output list, then the directive usage sentence, then input dorks — a sensible order. It is dense and dash-heavy, and the closing cancellation sentence is somewhat expendable, 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?

There is no output schema, so the description has to describe returns — and it does, in detail: key string example ('D minor'), tempo_map granularity (per-beat), downbeats in seconds, sections with times, chords on the beat grid, cues with start/end/tempo/key/level. Combined with the input guidance and latency/limits, an agent has everything needed to call it and interpret the result.

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 selection semantics the schema does not spell out as clearly: audio_key is 'an upload' while audio_url can be 'a result URL from another job as returned, or any public https URL.' The idempotency_key parameter is not mentioned in the description, though the schema documents it adequately.

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 opens with a specific verb stack and resource — 'Key detection, BPM/tempo detection, song structure and chords... musical analysis of a recording in one call' — then enumerates the exact outputs (key, bpm, tempo_map, meter, downbeats, sections, chords, dynamics, cues). It also distinguishes itself from the closest sibling by name: doseedo_detect_chords is for chord charts from separated stems, this is for one-call analysis of a mix.

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?

Explicit when-to-use: 'USE THIS to learn the key and tempo of a reference before writing a part — never guess or ask the user for what the audio already says.' Explicit alternative and exclusion: 'for a chord chart from stems use doseedo_detect_chords on the separated stems,' plus 'Cancel: not applicable' to steer the agent away from doseedo_cancel_job. Nothing is left to inference.

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

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

Annotations already disclose readOnly=false, openWorld=true, idempotent=false, destructive=false; the description goes further by explaining the async job_id flow, approximate runtime, downloadable session-zip result, and cooperative cancellation with partial refund/charge behavior. That is exactly the kind of operational context annotations cannot express, with 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?

Four sentences, front-loaded with the output and then the async/cancel mechanics; no filler. Every sentence contributes either the deliverable, the polling instruction, or cancellation/refund behavior.

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 24-parameter tool with no output schema but complete schema descriptions and annotations, the description covers the essential contract: input is a full mix, output is a session zip, execution is async, and cancellation has billing consequences. It is complete enough for correct invocation, even though sibling differentiation remains 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?

Schema coverage is 100% and the schema descriptions are highly detailed, so the baseline is 3; the description only summarizes the output (stems, tempo map, MIDI, chords) and does not add syntax or default semantics beyond the input schema. No parameter-specific guidance is needed here, but none is added.

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: turns an uploaded full mix into a complete multitrack DAW session, and lists the delivered artifacts (stems, tempo map, optional MIDI/chord guide) plus the downloadable zip. It does not distinguish this from siblings such as doseedo_session_from_stems or doseedo_separate_stems, so an agent must infer when this full-build path is preferable.

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 operational guidance for the async job (poll with doseedo_wait_task, ~4 minutes) and cancellation semantics, but never states when to use this tool instead of related siblings (e.g., already-separated stems vs. a full mix, or stems-only workflows). Usage is implied by 'uploaded full mix' but not explicitly scoped with 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?

Adds real context beyond the annotations: synchronous execution with a stated latency window, a 10-minute audio cap, and the fact that results come back in the submit response rather than via polling. It does not mention credit/cost implications (doseedo_quote exists as a sibling) or file size/format constraints, which is the main remaining gap for a paid, open-world submit call.

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

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

Front-loaded with the output contract, then inputs, then limits and the sibling alternative — every clause is functional. The output-field enumeration is dense and slightly run-on, but it earns its space given the absence of an output schema.

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

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

With no output schema, the description fully documents the return shape, and it covers the input alternatives, duration limit, synchronous timing, and the terminal-state caveat. An agent can call this and interpret the result without consulting anything else.

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 audio parameters and idempotency_key are already documented. The description restates the either/or relationship between audio_key and audio_url and notes the public-URL case, but adds little syntax or format detail 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 operation (beat detection / beat tracking) and enumerates the exact outputs it produces (bpm, beats[], downbeats[], beats_per_bar, beat_map, duration), plus a concrete usage framing: 'the grid to place a part against a recording'. It also differentiates itself from the closest sibling by routing full analysis to doseedo_analyze_song.

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?

Explicit about inputs (audio_key vs audio_url), the 10-minute audio limit, synchronous ~3–15 s behavior, and the alternative to use when key + sections + chords are also needed. It even resolves a question an agent would otherwise have to guess at: cancellation is not applicable because the job is already finished.

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 adds substantial behavioral context beyond the annotations: async job_id return, queued-until-desktop-picked-up state, no credits because rendering is local, named failing tracks with reasons, and detailed cancel semantics including refunds and dropped mid-render results. These are exactly the operational details an agent needs before invoking a long-running 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?

The description is dense but front-loaded: the main action and offline/real-plugin distinction come first, followed by constraints and async behavior. The long parentheticals and cancellation detail make it slightly heavier than necessary, though nearly every sentence carries useful 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?

For a complex async render tool with no output schema, the description covers the missing pieces: return shape (job_id, later stem URLs), polling tool, queueing dependency on Dø Desktop, track-render limitations, billing, and cancellation behavior. An agent has enough information 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 description coverage is already high at 83%, so most parameter meaning is provided structurally. The description reinforces that track_ids can target specific tracks and that results are downloadable stem URLs, but it does not explain format, tail_seconds, or idempotency_key beyond what the schema already says.

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 ('Bounce a session (or specific tracks) to audio') and distinguishes it from generic DAW rendering by explaining that it uses real plugin chains offline. It also differentiates from siblings implicitly by noting that headless renders are audio-only and that instrument/MIDI tracks require Logic open.

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 clear usage context: offline background rendering via Dø Desktop, headless audio-only limitation, need for Dø Desktop to pick up the job, and polling with doseedo_wait_task. It does not explicitly name alternative sibling tools such as doseedo_mix or doseedo_render_midi, so it stops short of full when-to-use alternative routing.

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 safety (readOnly, idempotent, non-destructive, open-world), and the description adds genuinely non-obvious behavior: large results are truncated to a 'brief' with rows cut to deciding fields, and specifying parts expands them. It does not mention error/failed states or whether the task record persists after completion.

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 in the first sentence, but the second sentence is a dense run-on packed with unexplained domain jargon ('a mix part's strip, rides (every point) and loudness') that costs more parsing effort than it returns.

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 4-parameter read-only check tool with no output schema, the description covers the return shape and the brief/full-result dichotomy well. The main gap is the absence of failure-state handling and any statement that either job_id or task_id+kind is needed, which the agent must infer from annotations and schema.

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. The description mostly restates what the schema says ('parts returns those rows IN FULL', job_id replacing task_id + kind), though it does add some meaning by explaining what 'full' entails for render_score and mix parts.

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 ('Check an async doseedo task once') plus what the reply contains (status, result file URLs/notes). The word 'once' implicitly contrasts with the polling/blocking sibling doseedo_wait_task, but it never names that sibling, so the differentiation is inferential rather than explicit.

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: you check a task returned by a submit tool, repeatedly if polling. There is no explicit when-to-use versus doseedo_wait_task or doseedo_list_jobs, and no guidance on retry cadence or what to do on a failed status.

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

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

Goes well beyond the annotations by disclosing the ETag provenance ('from the PUT response header; quotes optional'), the part-size rule ('all parts except the last must be the same size'), and the abort semantics. Minor gap: it doesn't say whether retrying with the same upload_id is safe, even though idempotentHint=true is declared, and abort's relationship to destructiveHint=false could be clearer.

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 tight sentences, front-loaded with the identity of the operation, then parameter guidance, then the abort alternative. No filler and no repetition of the title.

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

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

Covers the workflow position, the required part metadata, the size constraint, the abort path, and the return value ('the project_key'), which matters since no output schema exists. Nothing an agent needs 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?

With only 50% schema description coverage, the description compensates by explaining what the parts array must contain ('every uploaded part's number and ETag'), where the ETag comes from, and what abort does. upload_id and project_key remain undocumented in both places, so it isn't fully complete.

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 ('Finish a MULTIPART project upload'), ties it to the initiating sibling doseedo_get_project_upload_url, and names the downstream consumers (doseedo_convert_project / doseedo_import_project). An agent can place it precisely in the upload workflow without opening a schema.

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

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

Explicitly says this is the step after doseedo_get_project_upload_url and before convert/import, and names the escape hatch ('abort:true discards the upload instead'). When-to-use and the alternative path are both 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 annotations only saying non-readonly, non-destructive, open-world, the description adds substantial behavioral context beyond them: asynchronous job lifecycle, the transfer REPORT fields (`report`, `lossy`, `summary[]`, `warnings[]`), asymmetric target formats (Cubase/Studio One/Bitwig → .dawproject, Dorico → MusicXML), known lossiness (Cubase .cpr lacks audio pool, Dorico .dorico lacks notes), and the credit-refund rule. None of this contradicts the 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?

Purpose is front-loaded, but the remainder is a single dense paragraph of parenthetical clauses where critical operational steps (upload flow, async waiting, cancel/refund) are buried mid-text rather than surfaced. Every sentence carries information, but the lack of structure makes it harder to scan than its length warrants.

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, high-variance conversion tool with no output schema, the description covers input prep, direction semantics, target-format asymmetries, expected report fields, async handling, and failure/refund behavior. An agent has everything needed to invoke it correctly and interpret results.

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 operational meaning beyond the schema for project_key — zip a project folder so audio travels, a bare file also works, multipart past ~4 GB — and names the exact direction string pattern and per-family asymmetry. It does not, however, add much to the options object that the schema doesn't already spell out.

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?

Starts with 'DAW CONVERTER: a project rebuilt natively in the target' — a specific verb and resource — and enumerates exactly what travels (tracks, MIDI, audio clips, tempo, markers, plus automation/buses/plugin state for certain pairs). It explicitly distinguishes itself from doseedo_import_project (editing) and from session-based conversion, so an agent can tell it apart from siblings 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?

Explicit routing: 'To EDIT a project use doseedo_import_project; to convert a session the tools built: doseedo_download_session → upload that zip → logic2<target> (not a session_id).' It also states the prerequisite ('Upload first: doseedo_get_project_upload_url + PUT'), the async follow-up (job_id → doseedo_wait_task), and the no-stop cancel semantics, 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 beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true) by disclosing that the swap replays a transcription so small note differences are expected, that only swapped stems regenerate by default, that cancel refunds credits only if the render has not reached the GPU, and that result links are pre-signed and valid 24h with no auth header. This is exactly the kind of cost/irreversibility/workflow 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?

Purpose and the instrument-swap caveat are front-loaded, and the dense run-on later sentences (cancel/credit semantics, download instructions) each carry actionable information. It is heavy for a single paragraph and could be broken with line labels, but little 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 a 19-parameter async generation tool with no output schema, the description covers job lifecycle, polling, result delivery, verification and cancellation thoroughly. Minor gaps remain: it does not describe the shape of the eventual result beyond result.cover.instrument_swaps, and does not mention how name collisions or take re-runs should be handled beyond the schema's own note.

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% with rich per-parameter text, so the baseline is 3. The description adds genuine cross-parameter meaning for the instruments/regen interaction (swap separates, transcribes and replays the target stem while others pass through) that the individual schema entries do not fully state, but the bulk of parameter semantics lives in the schema.

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

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

States a specific verb+resource ('AI COVER / style transfer of a whole song: re-render an uploaded song as a cover') and names the two operating modes (timbre/instrument/lyric change, instrument swap). The 'whole song' framing implicitly separates it from the sibling doseedo_cover_stem without the agent needing to open a schema.

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

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

Gives strong operational context: poll with doseedo_wait_task, several minutes for full songs, default regen behavior for swaps, and the instruction to verify from result.cover.instrument_swaps rather than promise a note-perfect copy. It stops short of an explicit 'use cover_stem instead when you only need one stem' routing statement, leaving sibling selection 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 beyond the annotations: ~30–90 s async latency, pre-signed 24 h output URLs requiring no auth header, GPU-reached jobs still spending credits on cancel, and what result.recipe reports. However the description stresses a reusable idempotency_key returning the same job, which sits in tension with idempotentHint=false (the annotation describes default behaviour, the description describes an opt-in override) – a mild inconsistency an agent must resolve rather than a reversal of the annotation.

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 first sentence front-loads the purpose well, but the paragraph is dense with model plumbing (cond5, turbo graft, LatentPitch, vaescriptor, recipe keys) that most callers cannot act on, and the cancel/refund sentence is very long. The information is accurate but not pruned to what an agent needs before invoking.

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 15-parameter async generation tool with no output schema, the description covers the return path (takes[{url}], pre-signed download), the recipe provenance fields, and cancel semantics, which is close to sufficient. It does not mention cost/credit pricing per take, though the sibling doseedo_quote exists for that.

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 15 parameters in detail. The description mostly restates the schema's own points (midi:true adds a pitch roll, fidelity>0 leaks source sound) with only marginal added tradeoff nuance ("closer, but its sound leaks back in") and the cond5 FSQ+timbre training rationale. Baseline 3 is the right ceiling when the schema does the heavy lifting.

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 framing ("TIMBRE TRANSFER ... re-play ONE recorded part ... on another instrument") and immediately scopes it against siblings: a whole mix goes to doseedo_cover_song, exact notes go to transcribe + doseedo_render_midi. An agent can distinguish this from every neighbouring tool 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?

Gives explicit routing rules with named alternatives (doseedo_cover_song for a mix, doseedo_render_midi for exact notes, doseedo_instruments to source the instrument) plus the async follow-up chain (job_id → doseedo_wait_task → takes). It also states the cancellation/refund boundary, which tells an agent when cancelling is useful and when it is pointless.

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 the mutation safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description adds genuinely useful context beyond that: the session is created empty, and the call returns a session_id needed by downstream tools. No output schema exists, so naming the return value is a real contribution.

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 core action, followed by the useful workflow hand-off and return value. 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?

For a simple two-parameter creation tool with full annotations and full schema coverage, this covers the essentials. A minor gap: it doesn't explain the implication of the "daw" binding for later operations, though the schema enum and default largely handle that.

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 both parameters (name, daw enum with default logic) are fully documented in the schema. The description adds no parameter-level detail beyond that, 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 ("Create a new, empty DAW session") and the scope ("in the account"), plus what it returns. The word "empty" distinguishes it from siblings like doseedo_session_from_stems and doseedo_import_project, which also produce sessions.

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 names the follow-on tools (doseedo_edit_session to populate, doseedo_audio_to_session to target), giving the agent a clear workflow context. It does not state when NOT to use it (e.g., prefer session_from_stems when stems already exist), so it falls short of full when/when-not 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?

Goes well beyond annotations by explaining the soft-delete behavior, dry-run default, return value for dry runs, and that confirm:true is required for actual deletion. The destructiveHint is consistent because the operation removes sessions from the account, even though user disk files are untouched.

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 appropriately front-loaded with the action and safety model. It is longer than typical but every sentence supports correct, safe invocation for a destructive bulk operation.

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?

Covers the critical context for a destructive tool: dry-run behavior, return shape for dry runs, filter composition, and confirmation workflow. It does not describe the success response after actual deletion, but annotations and the 100%-covered schema reduce that gap.

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

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

Schema coverage is 100%, so parameter descriptions already do most of the work. The tool description adds useful semantics: ids come from doseedo_list_sessions, filters combine with AND, and confirm:true triggers actual deletion only after a dry run.

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 ('Delete DAW sessions in bulk') and immediately clarifies the soft-delete scope and that disk files are untouched. This clearly distinguishes it from sibling tools like get_session or list_sessions.

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 describes selection modes (ids or filters) and mandates the dry-run-first workflow. It tells the agent exactly when to proceed with confirm:true and includes a clear safety rule: 'Never delete sessions the user did not ask to remove.'

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 read-only/idempotent/non-destructive, and the description adds genuinely new behavior: the apply_mode "reopen" sequence (save, back up, close, apply, reopen), the logic_control macOS gate, and the not-connected path (how the user gets and pairs the app, what still works without it). These are traits not inferable from annotations. It omits cost/latency details, so 4 rather than 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?

Front-loaded with the core question, then the field inventory, then the failure case – well-ordered and dense. The parenthetical apply_mode expansion is worth its length, but the trailing 'Read-only.' duplicates the readOnlyHint annotation and is mild 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?

With no output schema, the description carries the return-value burden and does so: it names each reported field and explains the disconnected branch. An agent has enough to call it and interpret the result without further docs.

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 and baseline is 4. The description instead spends its words documenting return fields, which is appropriate for a paramless tool.

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?

It opens with a specific, answerable question (is Dø Desktop running, can it push edits into Logic) and states exactly what the tool reports: sessions held, apply_mode, logic_control, reopen_results, applied cursor. No sibling covers this diagnostic role, and the description makes that distinctive 'is my edit going to land now' framing explicit.

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 selection condition: 'Use it to know whether an edit will reach the project now or wait for the next session open,' which implicitly routes agents here before edit_session. It does not name when-not to call it or explicitly name the alternative tool, so it stops 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 only declare the generic safety profile (non-read-only, open-world, non-idempotent, non-destructive). The description adds the genuinely useful traits: GPU-backed vs CPU detector selection, the automatic fallback, the ~10-minute input limit, synchronous ~5–30 s execution, and an explicit 'Cancel: not applicable — result is returned in the submit response.' That last point is critical because doseedo_cancel_job exists as a sibling and an agent would otherwise try to cancel.

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 payload shape, then detector defaults, then input sourcing, then limits and timing. Dense parentheticals make it slightly run-on, but virtually every clause carries operational information (fallback, 10-min cap, sync timing, no-cancel).

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 correctly enumerates the return fields (chord_spans with confidence/beats, chords beat map, bpm, beats_per_bar, beat_map). Combined with the sync/cancel clarification and input limits, an agent has everything needed to call this correctly in one shot.

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 earns credit by explaining the default value semantics of deep (deep ACE with automatic CPU fallback) and the distinction between audio_key (an upload, ingest/) and audio_url (a prior result URL as returned, or any public https URL). These are behavioral implications the schema descriptions only partially convey.

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

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

States a specific verb and resource (chord detection on audio) and immediately disambiguates the output from siblings like doseedo_beat_grid and doseedo_tempo_map by naming chord_spans, chords, bpm, beats_per_bar and beat_map. An agent can tell exactly which analysis product this returns without opening the schema.

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

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

Gives concrete usage conditions: default is the deep ACE detector with CPU chroma fallback, deep:false forces the fast detector, supply audio_key or audio_url, 10-minute cap, and 'works best on a harmonic stem (piano/guitar/bass) or a clean mix' — which implicitly points at doseedo_separate_stems. It never explicitly names a sibling it replaces or excludes versus doseedo_analyze_song/doseedo_beat_grid, so it stops short of full routing guidance.

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

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

Beyond the annotations, the description discloses the short-lived no-auth download_url, the replay manifest contents, warning examples, and the ACTION-REQUIRED post-unzip place_local_files step. These are concrete behavioral traits an agent needs and are not available from the annotations alone.

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

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

The description is front-loaded with the core purpose and then covers return shape and required follow-up without obvious filler. It is dense and long, but most detail earns its place because there is no output schema.

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

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

For a complex download/build tool with no output schema, the description explains the returned download_url, replay manifest, warnings, and place_local_files follow-up well. The main remaining gap is input semantics, especially the required session_id.

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 only 50%: the daw parameter has a helpful enum description, but the required session_id has no description in either the schema or the tool description. The description focuses on outputs and post-processing rather than clarifying the 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 opens with a specific verb and resource: save a session as a native Logic project rebuilt server-side, with no desktop needed. It clearly distinguishes this from desktop-dependent flows, though it does not name the sibling alternative (convert_project) directly in the description; that routing detail appears only in 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 gives clear context for when this tool is appropriate: native Logic download, server-side rebuild, no desktop. It does not spell out explicit when-not-use exclusions, but the schema's daw parameter routes non-Logic targets to doseedo_convert_project.

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 annotations in useful ways: 'never cut mid-JSON' and 'all' (fitted, may shorten) disclose truncation/fitting behavior, 'an unknown name gets did_you_mean' discloses the error path, and 'no key needed' discloses auth. It also explains where operations land (live | next_open | state), which 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?

The default behavior is front-loaded in the first sentence and every clause carries information. The heavy parenthetical, em-dash-dense packing makes it harder to scan than necessary, but nothing is filler or redundant.

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 describes return shapes for every mode (default overview, op details, section views) and the truncation caveat. Combined with annotations covering safety and idempotency, an agent has everything needed to call it correctly and interpret results.

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%, yet the description still explains each parameter's effect: op/ops return entries in full, and every enum value of section is spelled out (recipes contents, ops in full, summary = field map + workflow + policy, all = fitted). It adds genuine semantics over the schema, including multi-value behavior via ops:[…].

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 (the catalog of session edit ops that doseedo_edit_session accepts) and its serving model ('views that each fit one answer'). It explicitly names the tool it supports, so an agent can distinguish it from doseedo_edit_session itself 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?

Strong sequencing guidance: 'read it ONCE before a build', then fetch by op/section, and 'copy one instead of discovering op order' for recipes. It does not, however, state when NOT to use it or contrast it with the sibling doseedo_recipes tool, which plausibly overlaps.

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 flag it as a non-read-only, non-idempotent, open-world mutation. The description adds substantial context beyond that: the 10–20 s save/backup/close/reopen cycle, validate-before-store contract with named error codes, atomic-vs-partial semantics, dedup behavior via batch_key, in-order application, and absence of per-batch undo. Slight remaining gap: no note on what a successful response returns beyond `deduped`/`rejected`.

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 purpose and information-dense, with CONTRACT and RETRY labels aiding scanability. However, it reads as one long run-on paragraph; some sentences (the ~10–20 s save cycle, the error-code list) could be tighter to reduce cognitive load, though none is truly wasteful.

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, stateful, no-output-schema mutation tool, the description covers purpose, prerequisites, side effects, error contract, idempotency, and verification. An agent has everything needed to call it correctly and interpret partial results without opening other docs.

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 75%, but the description meaningfully extends every key parameter: ops get their id/argument sources, atomic gains the all-or-nothing vs good-ops-only contrast, and batch_key gains the dedup-on-retry contract with a concrete example. This is more than the schema provides.

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 (Edit) and resource (DAW session) and enumerates the op domains (regions, MIDI notes, samples, tracks, mixer, plugins, tempo, markers, key). It routes the agent to companion tools (get_session for ids/values, edit_ops_reference for op arguments) so it is clearly differentiated from siblings.

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 describes when live sync happens (sync.live_edits true → desktop writes into Logic project, ~10–20 s, tell the user) versus when ops are stored and applied at next open. It also gives concrete retry guidance (re-send with same batch_key) and verification guidance (download_session replay). No guidance is left to inference.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is partly covered. The description adds substantial context beyond that: the async job lifecycle, ~40–150 s render time, bit-exact splicing of surrounding audio, the output.plan field, and precise cancel/refund behavior. It does not contradict any annotation.

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 long and dense, but it is front-loaded with the core operation and the length is justified by a 19-parameter tool with a multi-step async workflow. Heavy capitalization and parenthetical asides add some noise, but every section carries operational 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?

For a complex, async, 19-parameter tool with no output schema, the description covers the full lifecycle: input requirements, planning behavior, return shape (takes[{url}], output.plan), timing, and cancellation. An agent has everything needed to invoke it correctly and interpret the result.

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: it explains that the gap is in seconds of the audio sent, that bar_offset_seconds marks where a bar line falls, and that bpm/bar grid drive the fill. It also clarifies the practical requirement of including take audio on each side of the gap.

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

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

The description opens with a specific verb and resource ('INPAINT (repair) a part') and immediately defines the operation: send one recorded part with a gap, get it back with the gap played. It clearly distinguishes this from generative siblings like doseedo_generate_music or doseedo_render_midi by emphasizing that the surrounding take is kept bit-exact and the fill is generated against it.

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 states exactly when to use each fill mode ('context' for inpainting a span that has audio, 'loop' for a groove, 'written' for a composed part, 'auto' as default), gives practical guidance ('send 8 bars or more before it is best'), and spells out the async workflow via doseedo_wait_task with expected timing. Cancel semantics are also documented, 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?

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the safety story is partly covered. The description goes well beyond them with the async lifecycle (job_id → wait_task, 1–3 min), pre-signed URL handling and 24 h expiry, credit/refund semantics on cancel, and the honest warning that output can be near-silent, a drone, or clicks — rich behavioral context that the annotations do not carry.

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 decisive 'NOT A COMPOSER' framing, then workflow, then the caveat and async mechanics — a sensible order. It is dense and longer than typical, but nearly every clause carries routing or behavioral information; minor tightening of the instrument/recipe enumeration would help.

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, and the description compensates by explaining what comes back (audio URLs, expires_at, file naming driven by `name`) and how to cancel. Combined with 100% schema coverage and annotation-backed safety, an agent has what it needs; only the quality-variance caveat is left qualitative rather than quantified.

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 all eight parameters are already documented, setting the baseline at 3. The description adds some meaning the schema does not — that a key stated in the prompt is not honoured and that bpm/time_signature only tag the caption — but it does not walk through the remaining parameters (seed, duration_seconds, 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 states a specific verb and resource — text-to-music generation from a prompt alone, with no note data behind it — and explicitly carves out what it is not (a composer). It names the sibling tools (doseedo_render_score, doseedo_render_midi, doseedo_instruments, doseedo_recipes) it should be chosen over, so an agent can route correctly without opening any schema.

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

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

Explicit when-to-use ('only when the user explicitly asks for a prompt-only AI sketch'), explicit alternatives ('YOU write the piece' via score/midi paths, recipes compose-piece / score-a-film / compose-part), plus a hard caution to listen before delivery and never ship a take as the music. Both the positive and negative routing conditions are stated.

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

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

Goes well beyond the annotations by disclosing the async contract (job_id → doseedo_wait_task, typically 15–40 s), the return form (pre-signed audio URLs, usable with curl -OJ and no auth header, valid 24 h), and precise cancellation economics — refunded if not yet on the GPU, credits spent and output discarded if already rendering. The idempotency_key parameter is consistent with idempotentHint=false: dedupe is opt-in, not a property of 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?

Front-loaded with the purpose, then the kind rule, then the wrong-tool routing, then the async/cancel contract — a sensible order with no filler sentences. It is densely packed with parenthetical example lists, which is scannable but pushes toward the upper bound of useful length.

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 non-read-only, open-world, async generation tool with no output schema, the description supplies everything an agent needs: what gets produced, how long it takes, which follow-up tool completes the job, what the URLs look like and how long they live, and what cancel does to credits and output.

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 most parameter meaning; the description still adds the non-obvious coupling between prompt wording and kind inference, plus the hit/loop/texture behavioral distinction that the enum description only sketches. It does not, however, add anything for bpm, time_signature, seed, or idempotency_key beyond what the schema says.

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 ("Generate sound effects (SFX) from words with Stable Audio Open") and enumerates concrete output families — impacts, whooshes, footsteps, UI blips, ambiences, risers, one-shots. It also draws a hard boundary against the nearest siblings by naming doseedo_render_midi for note parts and doseedo_render_score for scored music.

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 when-to-use (SFX/foley for games, apps, video), explicit when-not (parts with notes or composed music, each routed to a named alternative), and a practical selection rule for the kind parameter (hit vs loop vs texture, with the server inferring it if omitted). It even includes a concrete anti-pattern — don't put tempo words in a hit prompt or the model writes a loop.

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 readOnly=false, idempotent=true, openWorld=true, destructive=false, so the description carries the operational burden and does so well: hard size caps per plan tier, the exact refusal error (project_too_large with the cap and an upgrade link), the 4 GB multipart threshold, per-part retry semantics, and the required follow-up step doseedo_complete_project_upload. The one blemish is mild internal tension between 'a single PUT takes up to 5 GB' and 'past 4 GB you get a MULTIPART upload', which leaves the real single-PUT ceiling slightly ambiguous.

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 a single dense paragraph, but it is front-loaded with purpose and size limits and every later sentence carries executable detail (curl lines, split, ETag capture, retry rationale). The 5 GB vs 4 GB statement is the one place where wording could be tightened rather than expanded.

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

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

With no output schema and a seven-parameter tool spanning a multi-step, resumable workflow, the description covers the entire lifecycle: initiating the presign, choosing the transport, executing the upload, and completing it via doseedo_complete_project_upload, plus the re-call path for additional part URLs. An agent can act correctly without consulting other 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: size_bytes is what selects single-PUT vs multipart and sizes the parts, and project_key/upload_id/part_numbers are only meaningful as a continuation of an earlier call. The curl/split recipes attach concrete operational behavior to each parameter rather than restating its type.

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 ('Get a presigned upload for a DAW PROJECT file') and immediately ties it to the consuming siblings doseedo_convert_project / doseedo_import_project. The one gap is that it never explicitly contrasts itself with the sibling doseedo_get_upload_url, which an agent must choose between; the distinction ('DAW project file' vs. a general upload) is only implied.

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 says exactly when to use it (before convert_project/import_project), how to package the input (zip a project FOLDER so audio travels with it, including .logicx/.band packages), and which mode to pick (single PUT vs multipart driven by size_bytes or the multipart flag). It also handles the non-obvious continuation case: re-call with project_key + upload_id + part_numbers when more part URLs are 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?

Annotations only cover the safety profile (readOnly/idempotent/non-destructive), and the description is consistent with them ('Read-only'). Beyond that it discloses behavior no annotation carries: the note inline/omission budget (≤200 notes, else note_count + notes_omitted:true), track-level pagination via `truncated` + `next` with the exact resume args, the 'never cut mid-JSON' guarantee, the sync.live_edits flag answering 'will an edit reach Logic now?', and markers being absolute beats from bar 1.

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, then payload, then budget, then next steps — a sensible order. It is a dense run-on with heavy parentheticals that hurts scannability, and the long inline field enumeration partially duplicates the doseedo_edit_ops_reference call it already points to, but nearly every clause carries usable 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?

No output schema exists, so the description carries full burden for a very complex return, and it does: top-level shape, id conventions, budget/degradation behavior, pagination contract, and the sync freshness signal. An agent can call it, interpret a truncated result, and continue without another discovery call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool meaning the schema cannot: `i` is what edit_midi_notes selects by, param_id is required by set_device_param, ch_b_… denotes sends/output, and the include_* flags are framed as interlocking budget fallbacks with the pagination path. That is genuine semantic value over the 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+resource ('Read a DAW session') and immediately frames it as 'the arrangement an agent edits against', then enumerates the exact payload (tracks with wire ids, regions, mixer, plugins, buses, tempo_map, sync). It also positions itself against siblings: it produces ids consumed by doseedo_edit_session and doseedo_render_midi. An agent can tell this is the read-state entry point, distinct from doseedo_list_sessions, 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?

Clear routing context: pass returned ids to doseedo_edit_session, a track_id to doseedo_render_midi, and consult doseedo_edit_ops_reference for the field map. It also gives concrete usage triggers for the knobs ('pass include_notes:true with tracks:[ids] for a track's notes'). No explicit when-not-to-use condition is stated, so not quite 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 only say it is a non-read-only, idempotent, open-world call; the description adds the actual mechanics: you must PUT raw bytes to upload_url with a matching Content-Type, a key comes back for four or more downstream tools, and source_url mode returns a key with nothing to PUT. It also discloses plan-dependent behavior (lossless session storage only on Pro+) and hard limits (film ≤ 2 GB, URL copy ≤ 256 MB) that no structured field carries.

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

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

Information is front-loaded with the return values stated before the routing detail, and the AUDIO / SCORE / FILM / ONLINE-URL markers make scanning possible. It is still a very dense block with a long nested-parenthesis opening sentence and a format list repeated verbatim from the content_type schema, so it is not maximally tight.

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 three-parameter tool with no output schema, the description supplies everything an agent needs: what is returned (upload_url + audio_key/video_key/score_key), which sibling consumes each key, size and format limits, plan caveats, and the local-file escape hatch. No meaningful gap remains 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% and all three parameters are documented there, including extension inference for content_type and the source_url copy semantics. The description reinforces the mode split (source_url vs PUT) and lists accepted formats, but that mostly duplicates the schema's own content_type description rather than adding new syntax or constraints.

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') and immediately enumerates the three distinct input modes it serves: own audio file, SCORE (→ score_key for doseedo_render_score), FILM (→ video_key for doseedo_spot_video / doseedo_score_to_picture). It names the downstream siblings each returned key feeds, so an agent can separate this from a plain upload or render tool.

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

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

Gives explicit routing rules: use this when the file is local or a public https URL, but do NOT upload for session samples/regions on this machine (use load_quick_sampler_sample sample_path / attach_audio local_path and place_local_files). It also names the alternative path (source_url) and its precondition (public https, ≤ 256 MB), and warns to send big scores as files rather than notes in the call.

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 annotations: reveals what is carried (tempo map, meter, markers, track mixer state, MIDI notes), what is NOT carried (audio media), how audio is surfaced (audio.placements, audio.next), that plugins/buses are reported not recreated, and that parsing takes seconds to minutes with a status:'running' continuation. This is unusually rich behavioral disclosure for a mutation 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?

Dense and front-loaded with the core action and return value first, then caveats about audio and plugins, then the upload/polling prerequisites. Long sentences with stacked parentheticals make it slightly harder to scan, but every clause carries real 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 still explains return values (session_id, status:'running', task_id, audio.placements/audio.next), prerequisites (prior upload), and processing latency. For a four-parameter tool with a multi-step async flow, nothing an agent needs 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 100%, so the baseline is 3; the description earns extra by explaining that project_key originates from doseedo_get_project_upload_url and by describing the task_id continuation loop in operational terms (re-call until session_id is returned). It does not add much about daw/name 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?

States a specific verb and resource ('Open an uploaded DAW project ... as an EDITABLE doseedo session'), enumerates supported formats, and names what it produces (session_id). It is clearly distinguishable from siblings like doseedo_convert_project or doseedo_create_session.

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 to upload first with doseedo_get_project_upload_url, and names the downstream flow (get_session → edit_session → download_session) plus the alternative for other DAWs (doseedo_convert_project). It also gives the continuation rule for task_id polling, so when/when-again is fully prescribed.

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?

Annotations already declare readOnlyHint/idempotent/non-destructive, and the description restates read-only as a confirmation rather than a contradiction. It adds ordering semantics (newest first) and, with no output schema present, describes row shape (artifact names per job). It does not mention pagination or the page-scoped nature of some filters, which the schema covers instead.

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 purpose and scope, then usage cases, then row shape and the cross-reference. Dense but every clause carries information; the parenthetical kind list is the only slightly bloated part.

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

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

For a read-only list tool with no output schema, the description supplies ordering, row contents, and the escalation path to full results, which is what an agent needs to act. Remaining gaps are cursor/pagination behavior and the page-scoped caveat on session_id filtering, both of which live in the schema.

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 80%, so the schema carries most parameter meaning. The description only gestures at filtering via the kind list, which even mixes registry names with short aliases ("generate", "stems", "session") rather than the schema's names, and says nothing about limit, before, or status.

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 ("List the jobs this account submitted") and enumerates the job kinds covered, including analyses. It explicitly contrasts itself with doseedo_check_task, so an agent can tell the two apart 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 three concrete situations to call this tool (finding an earlier result, checking what is running, resuming after a lost connection) and names the alternative for full details ({job_id} via doseedo_check_task). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered; the description adds genuine context beyond that by disclosing the conditional result set depending on whether Dø Desktop is connected. It stops short of describing ordering, size, or whether names are unique across stock and third-party plugins.

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 front-loaded sentences: purpose, result composition, then the actionable follow-up with an example payload. It is dense but every sentence carries information; the parenthetical 'stock + third-party' partly repeats the preceding clause.

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

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

With no output schema and no parameters, the description correctly shouldered the job of explaining what comes back — and it does, at the level of catalog vs. installed set. It could say more about the shape of each entry (name, type, vendor), which matters since the agent must match names exactly.

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 carries no semantic burden and the baseline is 4. The description does add useful adjacent semantics by naming the exact add_device argument the returned names feed into, tying output to downstream input.

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 (list available insertable plugins) and immediately names the consuming operation, doseedo_edit_session's add_device. It also distinguishes the two sources returned (stock Logic catalog vs. plugins actually installed when Dø Desktop is connected), which is far more than a restatement of the title.

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 routes the agent forward: after listing, insert with add_device {channel_id, device: {name: "…"}}, including the exact payload shape. What is missing is differentiation from the sibling doseedo_instruments, which plausibly overlaps, and any statement of when this list is unnecessary.

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, so the safety profile is covered. The description adds real value beyond that: result ordering, that the response carries total and next_offset, and that name_contains is a case-insensitive substring filter — useful since there is no output schema.

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

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

Two sentences, front-loaded with the primary action and scope, then paging and sibling routing. Every clause earns its place — no restating of the title or 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 compensates by describing the returned fields and the pagination envelope (total, next_offset). All three optional parameters are covered by the schema, and the sibling handoffs are named, so an agent has everything needed to call it 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 schema already documents defaults, max, and the next_offset chaining pattern. The description restates the same paging and filtering concepts without adding syntax or edge-case guidance, so the baseline of 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?

Specific verb plus resource ('List the connected account's DAW sessions') with a stated sort order and the exact fields returned (ids, names, DAW, update time). An agent can distinguish it from doseedo_get_session and doseedo_edit_session without opening any schema.

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

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

Explicitly routes onward: session ids feed doseedo_get_session and doseedo_edit_session, and doseedo_delete_sessions handles cleanup. It does not state when *not* to list (e.g. use name_contains rather than paging everything), so there is clear context but no explicit 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?

Annotations declare a non-read-only, open-world, non-idempotent mutation, and the description adds substantial context beyond them: async job_id with ~15–90 s waits, no stop for a running mix (credits spent, output discarded), refunds only for plane-queued failures, and 'no credits' for mixgraph edits. The idempotency_key note sits slightly at odds with idempotentHint=false, but it is an opt-in request key rather than a claim the tool is idempotent, so this is not a true 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?

Purpose and stems sourcing are front-loaded, and nearly every clause carries information, but the single sprawling block with nested parentheticals and a 25-item style enumeration is hard to parse on first read. It is dense rather than padded, but the structure could be split into clearer segments.

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 21-parameter tool with no output schema, the description covers the asynchronous lifecycle, cancellation and refund semantics, what the returned mixgraph contains and how to edit it, and even names result fields such as output.loudness and output.dialogue.lines. An agent has what it needs to call this 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 baseline would be 3, but the description adds real meaning: balance is dB on top of the levelling (+3 brings a melody forward), automation values are dB off the strip gain_db with 0 = as set and -60 = mute, mixgraph edits are partial against the stored mix, and target_lufs states the tolerance and clipping tradeoff.

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 pair and resource: each part levelled, panned, high-passed, reverbed, then mastered to a loudness target, returning a WAV plus an editable mixgraph. It also distinguishes itself from siblings by naming doseedo_render_score as the source of from_job and doseedo_session_from_stems as the downstream consumer.

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 explicit selection rules: use from_job after render_score, or pass stems directly; call again with mix_job plus only your edits to revise a mix; use dialogue/music_offset_s/length_s when mixing to picture. It also names the follow-on tools and the wait/cancel path.

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 readOnly/idempotent/non-destructive, and the description reinforces this with 'Spends nothing', which is exactly the behavior an agent needs to trust a dry run. It goes further with real behavioral detail absent from annotations: the gate is authoritative, refusals name the exact price, and 'refused'/'planned' semantics for render_score. It does not describe the returned estimate structure (cost fields, whether a breakdown is included), leaving some behavioral surface undisclosed.

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 strong: the purpose and zero-cost guarantee come first. However, the description re-enumerates all 24 enum values already fully specified in the schema, which is pure duplication, and packs job-specific arg rules into one run-on parenthetical spanning multiple sub-cases. Roughly a third of the text could be cut without information loss.

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

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

For a two-parameter, no-output-schema pricing tool, this covers intent, safety, arg relevance, and refusal behavior — enough to invoke correctly and interpret a refusal. Remaining gaps are modest: the actual shape of a successful estimate (what fields a cost estimate returns) is never characterized beyond 'the planes' own price table', and there is no indication of latency or rate limits for repeated quoting.

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 would be 3, but `args` is a free-form object with additionalProperties, and the description meaningfully constrains it by naming the price-relevant keys (duration_seconds, models, instruments, notes/bpm, voice_split) and giving pricing rules the schema cannot express — takes free, voices cost one batch per ~6. The phrasing is dense and some clauses (tempo_map vs duration_seconds precedence) require re-reading, which costs a point.

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 a second dimension (affordability), and immediately distinguishes itself from the sibling job tools via 'BEFORE submitting it' and 'Spends nothing'. An agent can tell this is a dry-run pricing call, not a job submission, without opening the schema.

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

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

Gives clear when-to-use guidance: call before submitting, pass the same args you would give the job tool. The alternative (invoking the job tool directly, spending credits) is implied by 'Spends nothing' and 'BEFORE submitting'. It does not explicitly state when not to use it — e.g. that it can't replace the job tool itself or that doseedo_account is the place for balance history — so it stops short of full routing coverage.

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?

With annotations only covering the read/write/safety profile, the description carries rich behavior: fit versus fill (blurred-fill preservation vs centre crop), audio preserved untouched, 1080 px short-side cap with no upscaling, H.264 MP4 output, and passthrough copy when the video is already in that frame. It also discloses the important operational facts — CPU with no credits, async job_id, and that a running re-frame cannot be stopped (credits spent, output discarded, only queued jobs refunded). The idempotentHint=false alongside an idempotency_key parameter is a nuance rather than a contradiction, since the key makes retry-safety opt-in.

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 in the first clause and every operational fact (fit semantics, format, credits, async, cancel) is present. There is some redundancy — the four aspect ratios and their use cases are restated from the schema's enum descriptions, and the cancel explanation is a long parenthetical chain — but little is genuinely 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?

For a mutation-style render with no output schema, the description supplies everything an agent needs: accepted inputs and their provenance, output container and resolution ceiling, cost model, async hand-off to doseedo_wait_task, and the cancellation/refund outcome. Nothing essential to calling it correctly or setting user expectations is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains that fit (the default) centres the picture over a blurred fill of itself so captions survive, and that fill centre-crops with the report stating how much of the picture was kept. It also clarifies where video_url may legitimately come from. The name and idempotency_key parameters are left entirely to the schema, which keeps this below 5.

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?

"REFRAME A VIDEO: the same video in another frame" gives a specific verb and resource, and immediately enumerates the four target frames with their real-world use cases (stories, reels, shorts, feed, square, landscape master). An agent can distinguish this from doseedo_score_to_picture or doseedo_bounce_session without inspecting any schema.

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

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

It names the concrete situations each aspect ratio serves and the two acceptable input sources (an upload video_key, or a video_url obtained from doseedo_score_to_picture or any public https URL), plus the async follow-up route via doseedo_wait_task. What is missing is an explicit exclusion — nothing says when to reach for a sibling instead, e.g. when re-framing is unnecessary because the video is already correct.

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 (~1–3 min), takes returned best-first, pre-signed 24-hour URLs, note-fidelity caveats, credit refund behavior on cancellation, and detailed drum/synth engine outcomes. These details are substantive and do not contradict the supplied readOnly/openWorld/idempotent/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 and core input modes are front-loaded, but the description is very dense and repeats schema-level material such as the GM drum pad mapping and note object fields. It is comprehensive and structured, yet portions could be trimmed or left to the schema descriptions.

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 must carry return behavior; it does so by explaining job_id, doseedo_wait_task, takes with rank/score, pre-signed URLs, seed, duration, voices, refine, chain, and cancellation outcomes. That is complete for a complex 34-parameter render 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?

With 100% schema description coverage, the schema already defines each parameter. The description still adds meaningful cross-parameter routing: input must be exactly one of notes[], midi_url, or session_id + track_id, and notes are sent as given with no pitch snapping or quantizing. Most per-parameter detail is rightly left to the schema.

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

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

The opening sentence names the exact transformation (MIDI to audio) and the resource (an AI virtual instrument playing a written part). It clearly distinguishes this from doseedo_analyze_midi, doseedo_instruments, doseedo_wait_task, and doseedo_train_instrument by assigning each sibling its role.

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 explicit routing: run doseedo_analyze_midi first for a free harmony check, use doseedo_wait_task for async jobs, pull instrument ids from doseedo_instruments, and use doseedo_train_instrument for custom lora_id. It also explains when to choose drum_engine "oneshot" versus "model" and synth_engine "oneshot"/"performed"/"model" based on genre and acoustic versus electronic context.

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 hard caps (≤32 lines, ≤96 player rows, ≤600 s), cost behavior ('Each player renders (and costs) like a part'), a failed part being re-rolled once, and a precise cancellation policy distinguishing jobs not yet on GPU (refunded) from in-flight renders (credits spent, output discarded). It even describes the result object's receipt fields, which no output schema provides.

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

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

Purpose is front-loaded and the ★ SECTIONS marker helps, but the body is a single very long paragraph with dense em-dash clauses and abbreviations that a reader must re-parse. Several passages duplicate schema descriptions (GM drum pads, lyrics syllable rules, dynamics automation) rather than adding value.

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 16-parameter, deeply nested, no-output-schema render tool, it covers what is needed: input alternatives, limits, timing, per-part result fields with fit.verdict/coverage and lora.applied, mix_url, and the async/cancel lifecycle. Almost nothing an agent needs to call this correctly is left unstated.

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 per-parameter semantics; the description nevertheless adds cross-parameter meaning it cannot express — file parts matched by name then GM program, instruments{} keyed by name or 0-based index winning over that match, and a chord on a one-line instrument splitting into one stem per voice. Some sections (lyrics, dynamics lane, drum pad map) merely restate 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 first sentence states a specific verb and resource ('plays a whole arrangement you wrote in one call') and immediately scopes it with concrete genres. It also names the boundary case explicitly ('Synth parts: doseedo_render_midi'), so an agent can separate this from the MIDI and generic-generation siblings.

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 spells out the alternative input paths (parts[], midi_url, musicxml_url) and when each applies, plus concrete selection rules: players 2–8 for a section versus a soloist, drum_engine 'model' for acoustic kits versus 'oneshot' for drum machines, and real-drum genres that must stay on the model. It also hands off the next steps (doseedo_mix then doseedo_session_from_stems) and the async path (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 only mark it non-readOnly, openWorld and non-idempotent; the description supplies the real behavioural picture: mux with no re-encode, CPU with no credits, dialogue detection by VAD or supplied spans, measured delivery report, and — critically — that a running delivery cannot be stopped, burns credits, ends as canceled with output discarded, and is only refunded when still queued at the plane.

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 purpose then workflow, and nearly every clause carries decision-relevant content. It is nonetheless a dense single block with heavily nested parentheticals and an inline tracks sketch that duplicates the schema, which costs some 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?

Despite 11 parameters, nested objects and no output schema, the description covers inputs, the split-soundtrack workflow, duration limits, async handoff, cancellation/refund behaviour, and the returned artefacts and measurement report. An agent has what it needs to call this correctly on the first try.

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 meaning: audio_url must be a doseedo_mix mix_url or any public https URL, role defaults to music and is ducked, tracks cap at 64, start_s negative means the head is cut at the first frame, and production_audio:"keep" also drags the film's own music under the score. It does not re-cover the finer fade/source_start_s knobs the schema documents, which 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 and resource with scope: lay mixed cues on the picture at SMPTE timecode, with ducking, loudness normalisation and mux. It explicitly identifies itself as "the last step of scoring a film" and names the surrounding siblings (doseedo_mix mix_url, doseedo_split_soundtrack, doseedo_spot_video), so it is distinguishable without opening any schema.

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

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

Gives concrete when-to-use routing: use it after mixing, split first with doseedo_split_soundtrack if the film already has music and lay dialogue/effects stems back with production_audio:"drop", or lay the old music back with duck:false. It also names the async path (job_id → doseedo_wait_task), the 25-minute reel limit, and the cancel/refund rule, 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?

Annotations only declare the operation is not read-only and open-world; the description goes far beyond by disclosing the async job_id model, the ~2 minute poll loop, that cancellation does not stop a running separation (credits are spent and output discarded), and that only plane-queued jobs get a failure refund. It also enumerates the exact result keys (stems, midi, drum_substems, vocals_lyrics, session_tracks, models_effective), so the agent knows what comes back despite there being 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?

Purpose is front-loaded in the first clause and every subsequent clause carries operational information (async flow, result keys, cancel economics). It is dense and parenthetical-heavy — one long block rather than separated sections — which costs some scannability, but little of it 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 a 13-parameter, no-output-schema, expensive async job this is unusually complete: input sourcing (audio_key vs audio_url, 256 MB fetch limit), model selection, derivative outputs, result field inventory, polling path, and cancellation/refund behavior are all covered. An agent could call and follow up on this tool correctly from the description alone.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema only states piecemeal: stems_only implying include_midi:false, session_id requiring parent_track_id and yielding session_tracks/session_tempo_bpm, and guitar_split/other_classification outcomes flowing into named result fields. The optional idempotency_key semantics are also spelled out in behavior terms (same job returned after a timeout).

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 ('split an uploaded mix into stems') and enumerates the outputs (vocals/drums/bass/guitar/piano/other or orchestral sets), plus a secondary framing ('vocal remover', acapella vs karaoke backing). That is enough to distinguish it from neighbors such as doseedo_split_soundtrack or doseedo_transcribe 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?

It gives real context: use it to isolate vocals or produce karaoke backing, use stems_only for the fastest/cheapest run, use models=orchestra with instruments for wider sets, and poll with doseedo_wait_task. What it lacks is an explicit exclusion statement — nothing says when to prefer doseedo_split_soundtrack, doseedo_transcribe, or doseedo_session_from_stems instead.

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 say non-readOnly, non-destructive, non-idempotent and open-world; the description adds the operational facts an agent actually needs beyond that: async job semantics with a 30-90 s wait, a pre-signed zip URL that expires in 24 h, credits that are spent even if the job is abandoned, that a running build cannot be stopped, and that only a queued job is refunded. It also discloses secondary behavior such as video re-encoding to 720p, the video appearing only as a muted track in REAPER/Logic, and Ableton projects being built without video.

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 opening sentence front-loads the deliverable and the source/target choices, so scanning yields the essentials quickly. It is dense — the run of clauses about cues, tempo maps and reference tracks in one sentence, plus a long trailing paragraph on cancellation and refunds, costs a little readability, but almost every clause carries distinct 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?

For a 15-parameter, nested, async rendering tool with no output schema, the description covers the workflow, the return artifact (pre-signed zip named <name>_session.zip) and the failure/cancel economics, which is nearly everything an agent needs. The only gap is that it says nothing about the shape of an error or partial-failure response, which matters for a job that can spend credits and be discarded.

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 does not carry: stems URLs may be result links used as-is, cues replaces from_job/mix_job/stems and caps at 12 cues with bar-1-on-a-bar-line joining, target defaults to logic, and mixgraph applies only gain_db and pan (its EQ, compression, reverb and rides are discarded). The idempotency_key and session_beats interplay is left to the schema, which keeps this off a 5.

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 deliverable ("Build a native DAW PROJECT from stems") plus the concrete artifacts (one audio track per stem from bar 1, optional MIDI tracks, on your tempo) and the three output formats (.logicx, .als, .rpp zipped). It is clearly separable from siblings like doseedo_render_score and doseedo_separate_stems because it consumes their output rather than producing audio.

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 three explicit entry paths with the condition selecting each: pass from_job plus a doseedo_render_score job_id, pass raw stems [{name, audio_url}] from renders/separations, or add mix_job after doseedo_mix. It also names the mandatory follow-up (doseedo_wait_task ~30-90 s) and explains the cues alternative for multi-cue films, so an agent never has to guess which parameter set applies.

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 generic profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds substantially beyond that: async job_id → doseedo_wait_task, a runtime estimate of roughly one third of soundtrack length, and the cancel/refund rule that a running split cannot be stopped and its credits are spent. The one real gap is that it never says the call spends credits up front or what happens to the returned job when the run fails — but the cancellation and refund semantics it does disclose are the kind of operational detail annotations cannot carry.

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 in the first clause and every subsequent block carries load-bearing content: routing branches, quality caveat, async timing, cancel policy. It is dense and parenthesis-heavy (nested quotes, em-dashes, colon chains) enough that a reader has to work, but nothing is filler and no sentence could be dropped without losing a real decision input.

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 it well: it enumerates the report contents (music present, spans in seconds, coverage, dialogue locations, per-part levels, music-under-dialogue depth). The quality caveat (dialogue clean, some percussion bleeding into effects at about −10 dB) is exactly the kind of expectation-setting a caller needs. It stops short of describing the job object fields a caller must poll, which keeps it off a 5.

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 all six parameters are already documented, and the description mostly restates them (video_key from doseedo_spot_video, key-or-URL alternatives). It does add one constraint absent from the schema — one reel per call, ≤ 30 min — which justifies staying at the baseline rather than falling below it.

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 ("split a film's soundtrack") plus the exact output shape: three DME stems that sum back to the source, plus a report. It distinguishes itself from the sibling doseedo_separate_stems by scope (whole film soundtrack vs. music-only separation), so an agent can pick between them 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?

Gives an explicit trigger ("use it before scoring a film that already has music") and then three named branches — REPLACE via doseedo_score_to_picture with production_audio:"drop", REMIX/RE-ORCHESTRATE via doseedo_separate_stems / doseedo_transcribe / doseedo_analyze_song, KEEP by scoring where the report shows no music. It also routes the async handoff to doseedo_wait_task and the cancel question to the absence of a stop call, which is exactly the when/when-not guidance the dimension asks for.

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 readOnly=false, openWorld=true, non-idempotent and non-destructive; the description goes far beyond that with the operational facts an agent needs: it is async (job_id → doseedo_wait_task), ~1 min for a 10-min 1080p reel, CPU-based with no credits for the analysis itself, hard input limits (≤ 2 GB, ≤ 3 h), and the credit consequences. The cancellation clause is unusually candid — a running spotting pass cannot be stopped, credits are spent, output is discarded, and only jobs still queued are refunded — which directly warns against a destructive-cost mistake. It even discloses a limitation ('sees light, movement and editing, not meaning') that shapes how the caller must interpret results.

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 correctly — the film-in/cue-sheet-out framing and 'first step of scoring to picture' land in the first clause — but the body is one very long, semi-colon-chained paragraph with no headings or line breaks. Output enumeration, input constraints and the cancel/refund policy are all run together, so an agent scanning for the cost warning must read past dense shot-detection detail. Nearly every clause carries information, but the lack of structure makes it harder to use than its content warrants.

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 no annotations covering cost, so the description must define the return payload itself — and it does, in detail: per-shot brightness/colour/motion/mood with keyframe JPEGs, scenes with arrival and pace, a storyboard, Silero VAD dialogue positions, intensity sections with rel levels, and cues with SMPTE timecodes, emotion, energy, tension arc, ranked hit points, suggested bpm and tempo_map_input. For a 10-parameter, credit-spending async tool it also states inputs, limits, the handoff chain, and the failure/refund semantics. Nothing an agent needs to call it correctly or interpret its result 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%, so the schema carries the baseline; the description nonetheless adds meaning beyond it, notably that video_key comes from doseedo_get_upload_url and accepts mp4/mov/m4v/webm/mkv (not stated in the schema), that tempo_map_input should be passed to doseedo_tempo_map 'as is', and that keyframes=0 disables scene frames and the storyboard as well. The prose restates defaults for coverage, reel and start_timecode that the schema already documents, which caps it below 5.

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+artifact: 'a video in, the music editor's cue sheet out', and immediately positions it as 'the first step of scoring to picture'. It explicitly distinguishes itself from downstream siblings by naming doseedo_tempo_map, doseedo_render_score, doseedo_mix and doseedo_score_to_picture, and it states the scope boundary ('sees light, movement and editing, not meaning'), which no other sibling claims.

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 usage context and an explicit pipeline: spot → doseedo_tempo_map per cue → write notes → render_score → mix → score_to_picture, plus the async handoff to doseedo_wait_task. It also says what 'spotter: model' is for versus 'rules' and when to raise/lower coverage. It never names a condition under which an agent should NOT use this tool (e.g. audio-only material belongs to doseedo_analyze_song or doseedo_split_soundtrack), so it stops short of full when/when-not routing.

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 material context beyond them: it is pure math, free, instant, and needs no key, and it discloses that unlandable soft hits come back landed:false with nearest_beat rather than as an error. It also describes the returned tempo_map and hits shapes even though no output schema exists.

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

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

The core purpose is front-loaded in the opening clause, and every sentence carries useful information about modes, outputs, or timecode handling. The description is dense and somewhat long for a single block, with several parenthetical examples, but it avoids true 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 12-parameter tool with no output schema, the description is complete enough: it covers the main scoring-to-picture use case, the fixed-tempo mode and its tolerance behavior, supported frame rates, and the returned tempo_map and hits arrays. It also identifies the downstream tools that consume the output.

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 interpretive meaning beyond the schema: a hit-level bpm means the tempo from that hit onward until another hit names a new tempo, and max_deviation_bpm is illustrated with a concrete example of 124 ±12% versus 3. It does not explain every parameter, but it meaningfully clarifies the interplay among hits[].land, hits[].bpm, fixed_bpm, tolerance_ms, and bpm_range.

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 gives a specific verb and resource — turn hit points into a tempo map that lands each hit on a downbeat, beat, or eighth — and distinguishes the output from downstream render tools by naming doseedo_render_midi, doseedo_render_score, and doseedo_session_from_stems. An agent can tell exactly what this 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?

It clearly frames the primary use case (scoring to picture) and gives concrete modes: variable tempo when the cue's pace changes and fixed_bpm: true for an ad or any cue that must hold one tempo. It names downstream consumers, but does not explicitly compare against sibling alternatives such as doseedo_score_to_picture or doseedo_spot_video.

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?

Goes well past the annotations by disclosing the async job_id contract, the polling tool (doseedo_wait_task) and expected ~15–60s duration, plus the cancellation reality: no stop for a running job, credits spent, output discarded, refund only if still queued. That cost/cancellation disclosure is exactly the kind of context annotations cannot carry.

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 output shape, then labeled segments ("Async:", "Cancel:") for scanning. The cancellation/refund sentences are a bit verbose and repeat the verb "runs"/"plane" phrasing, but each carries non-obvious operational 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?

For a 14-parameter async transcription tool with no output schema, the description still covers what is returned (pitch, onset/offset seconds, velocity, confidence), how to obtain it (poll job_id), how to source audio, and what happens on failure/cancel. Nothing an agent needs 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?

With 100% schema coverage the baseline is 3, but the description adds workflow-level meaning the schema only hints at: audio_url may be any public https URL or a doseedo result URL exactly as returned, enabling chaining of generate/stem outputs. The remaining 13 params are left entirely to the schema.

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

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

States a specific verb and resource ("AUDIO TO MIDI transcription") and immediately bounds the output (notes as JSON, not a .mid file). It names the sibling tools that handle the excluded cases (doseedo_separate_stems, doseedo_audio_to_session), so an agent can distinguish it 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?

Explicit routing: melody/bass/part → this tool; per-stem .mid files → doseedo_separate_stems or doseedo_audio_to_session; whole-mix key/tempo/chords → doseedo_analyze_song. It also spells out the two accepted input sources, so the when-to-use decision is fully determined.

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, but the description goes well beyond them: it discloses the hard 50-second server-side hold cap, the polling contract, the still_running flag, and the shape of a finished reply (output, pre-signed artifact links, note). This is exactly the behavioral context an agent needs to loop correctly instead of assuming one call suffices.

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

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

Three sentences, front-loaded with the core action and then the loop rule and return shape; nothing is padding. The nested parentheses (range, per-kind ETAs) make it dense to scan but each fragment carries real 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 takes on the return-value burden (output, pre-signed artifact links, note, still_running). It omits failure/expiry behavior — what a failed or expired job returns and what the agent should do then — which is the main remaining gap for a polling 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%, so the parameter meanings are already documented; the description nonetheless adds decision-relevant context by tying timeout_seconds to the submit reply's stated ETA and giving per-kind latency figures that drive that choice. The job_id-versus-task_id+kind relationship is left to the schema, which already states it, so this stays a modest add rather than a full re-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 opens with a specific verb and resource: 'Wait for an async doseedo job to finish', then adds the mechanism (server-side polling) and the terminal outcomes (result or latest status). It implicitly separates itself from a one-shot status check by describing blocking/polling, but never names the sibling doseedo_check_task, so the distinction has to 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?

It gives concrete operational guidance: if the reply has still_running:true, call again, and a submit reply's eta_seconds tells you how many calls a job needs, with per-kind examples (~15 s, 1–3 min, ~4 min). What is missing is routing guidance against alternatives — when to use this versus doseedo_check_task or doseedo_list_jobs if you do not want to block.

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