Doseedo DAW Sessions: read, edit and convert Logic, Ableton, FL Studio and Pro Tools projects

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 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 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?

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 already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, yet the description adds substantial context: the save/backup/close/reopen side effect with a ~10-20 s duration and an instruction to warn the user, the all-or-nothing atomic contract, the enumerated rejection codes with extra payload (did_you_mean, valid ids), and the absence of per-batch undo. The retry/dedup explanation is also consistent with idempotentHint=false (dedup only with an explicit batch_key) rather than contradicting it. Slightly short of 5 only because return shape and what a successful response looks like is left implicit.

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 well front-loaded: capability, then input sources, then live-edit side effect, then CONTRACT/RETRY/ordering sections in labeled blocks. The op-type parenthetical list is long, and the trailing '…' is a minor untidiness, but nearly every sentence carries operational information an agent would otherwise have to guess.

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 destructive, open-world batch-mutation tool with no output schema, the description covers the failure contract, error codes, atomicity, retry/dedup, ordering, absence of undo, and a verification path. Combined with a partially described schema, an agent has everything it needs to call this safely or route the agent to the right 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 75%, so the schema already documents ops, atomic and batch_key; the description still adds real meaning by spelling out the dedup-on-retry semantics of batch_key and the 'stores the good ops, rest rejected' behavior of atomic:false. It does not document session_id, but that is self-evident from the naming and the pointer to doseedo_get_session.

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 ('Edit a DAW session') and immediately enumerates the edit surface (regions, MIDI notes, sampler samples, tracks, mixer, plugins, tempo, markers, key). It is clearly distinguishable from the read-side siblings doseedo_get_session and the documentation-only doseedo_edit_ops_reference, which it names explicitly.

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

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

States precisely where inputs come from ('ids and current values from doseedo_get_session, op arguments from doseedo_edit_ops_reference') and where to verify results ('verify with doseedo_download_session'). It also gives the conditional branch for sync.live_edits true vs false, so the agent knows when the call mutates the live Logic project versus a stored copy.

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?

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 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.