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

With destructiveHint=false, idempotentHint=true and readOnlyHint=false already declaring the safety profile, the description adds real context: the persistence target (kuruitsugizaki.json), the fact that a set mutates stored config, and the existence check returned for detected paths. It does not discuss permissions or failure behavior, but the core behavioral traits are disclosed.

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, followed by usage triggers, then the mode semantics and the prohibition. Every sentence is functional and none is padding, even though it is a single dense paragraph.

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 explaining the return shape of the no-argument call ('every key with its value or the path detected for it, and whether that path exists'). All three call modes, the storage file, and operational guidance are covered, so an agent has everything needed to invoke 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 description coverage is 100% and each parameter is already documented, so the baseline is 3. The description's 'key alone / key and value' mapping reinforces the schema's semantics but adds little beyond what is already written in the property descriptions.

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

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

The description names the resource concretely — the machine-local paths the server needs (FL, loopMIDI, FL's Hardware folder, preset libraries) persisted in kuruitsugizaki.json — and then spells out the three operating modes (list-all, read-one, set-one). It is specific about what the tool does, though it never explicitly contrasts itself against siblings like fl_probe or fl_install; that differentiation 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 gives explicit triggers ('call it first in a new install', 'whenever another tool answers that a key is not set') and an explicit prohibition with an alternative action ('Never guess a path or search the disk... ask the user where it is, then set it'). An agent knows both when to reach for it and what not to do 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?

Goes beyond the annotations by disclosing the return shape ({ok, value} vs {ok: false, error}), that a setter mutates the open project 'as an edit by hand would', that nothing is saved, and that FL must already be running. The destructiveHint=true annotation is consistent with the setter caveat. It stops short of stating whether partial failures or invalid fn names are recoverable, but the added context is substantial.

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

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

Front-loads the core action and return contract, then layers usage routing and preconditions. Every sentence carries distinct information with no restatement of the name or 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 supplies the return contract itself, plus precondition (FL open), mutation semantics (edit-like, unsaved), and routing to alternatives. Nothing an agent needs before invoking a generic API-dispatch tool 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 'fn' (module.function) and 'args' (positional array) are already documented with examples in the schema. The description adds only an illustrative use case ('a parameter name or a mixer level') rather than deeper semantics, so baseline 3 applies.

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

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

States a specific verb ('call one function of FL's scripting API') plus the exact return envelope, and positions it against siblings: fl_exec for multiple calls/logic, project_read and project_write for .flp contents. An agent can distinguish this from any other tool in the list 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 selection criteria: use this for 'a single read or change', fl_exec for several calls or logic, project_read/project_write for anything the .flp holds. It also names a precondition — FL must be open and is not started for this — so the agent knows when the call will fail.

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 sandbox restrictions (no files, sockets, pipes), that changes act on the open project and are not saved, and the exact return shape for success and failure. The destructiveHint=true annotation is qualified rather than contradicted — mutations are real but discarded — which is valuable context. Minor gap: no mention of timeout behavior or long-running code.

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

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

Front-loads the core purpose and keeps every sentence load-bearing, but the later clauses are packed with multiple semicolon-joined facts in a single sentence, making it slightly denser than necessary.

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 no output schema, the description fully documents return values, the error/traceback form, sandbox limits, persistence semantics, and the FL-must-be-open prerequisite. 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 code, out, and timeout are already documented. The description reinforces the `result` assignment convention but adds no syntax, format, or edge-case detail about `out` or `timeout` beyond what the schema states, so baseline 3 applies.

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

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

Starts with a specific verb+resource ('Run Python inside the running FL's embedded interpreter') and enumerates the importable modules. It also names the sibling it differs from ('one call is simpler with fl_call'), so an agent can pick it out of a crowded toolset 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 selection rule: use this when work needs several calls or logic, otherwise prefer fl_call. It also states the prerequisite ('Needs FL open; it is not started for this'), which is exactly the when-not guidance an agent needs.

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

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

The annotations already declare mutation, destructiveness, and idempotency, and the description adds meaningful operational detail: it replaces an older controller script, conditionally creates and assigns a loopMIDI port, and explains registry-rewrite behavior. The note about FL being open and the returned midi guidance further reduces ambiguity.

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 main action and then uses a clear numbered structure for the two effects. Despite covering a complex install flow, every sentence carries useful operational information and there is no filler.

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

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

For a destructive, stateful setup tool with no output schema, the description is complete: it covers prerequisites, side effects, registry caveats, the returned fields, and the recommended next call. Nothing essential for correct invocation is omitted.

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 no parameters, so the baseline is 4. The description does not need to explain parameter semantics, and it correctly focuses on behavior and return value instead.

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: setting up the live link to FL. It immediately enumerates the two concrete setup actions, so the tool is distinguishable from fl_probe and other 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 gives explicit usage conditions: needed once per install and again after the folder moves, with the prerequisite to close FL first. It also names the follow-up tool fl_probe, so the agent knows the next step in the workflow.

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

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

Annotations say readOnlyHint=false but not why; the description fills that gap by disclosing the actual side effect — when FL is closed it launches FL (and loopMIDI) to test the link, then closes it again. It also clarifies scope ("Reads nothing from the project") and names the response fields launched_fl_seconds and closed_fl, so the agent knows a slow call is expected behavior rather than a hang.

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 check-and-return contract, then the call conditions, then the side effect — a sensible order with no filler. The clause "launched_fl_seconds says how long FL took, closed_fl that it was closed" is elliptically compressed and takes a re-read, which keeps it just below a 5.

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 full burden of describing return values — and it does, listing the version fields, pid, pipe handle, error shape, and the two launch/close indicators. Combined with the failure-recovery guidance, 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?

The tool takes no parameters and the schema is empty at 100% coverage, so there is nothing for the description to clarify. Baseline 4 applies; no parameter guidance is needed or missing.

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

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

States a specific verb and resource ("Check the live link to FL") and enumerates exactly what it returns: scripting API version, embedded Python version, pid, pipe handle, or a descriptive error. It also names the sibling live tools (fl_exec, fl_call, fl_transport, project_write) so an agent can place it in the tool set 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 explicit triggering conditions: call it first when a live tool fails, and after fl_install. This is a precise when-to-use rule tied to named siblings, not an implied one.

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 and idempotentHint=true, and the description's 'replacing earlier ones' is consistent with that. It adds substantial useful context – detached execution, timing, harness-saved-and-closed behavior, refusal when user FL is open, and the return shape – which is meaningful beyond annotations. However, several of these (return shape, follow-up loop) are more procedural than behavioral-safety disclosure, so a 3 is appropriate rather than the top of the range.

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: the core action and artifacts come first, prerequisites and caveats follow. A few sentences are lengthy (the FL closed-while-rendering note), but every sentence carries operational information. Slightly long, but no filler.

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

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

Although there is no output schema, the description spells out the return object {ok, rendering, log, saved_open_project} and the follow-up protocol (poll render_report until it stops saying rendering). For a detached, stateful render tool, an agent has everything needed to call it correctly and handle the async 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% and all three parameters are fully described in the schema (key, path, reopen), so the schema does the heavy lifting. The description does not add syntax or meaning beyond the schema for these parameters. 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?

Specific verb and resource (render an .flp to audio) plus the exact artifacts produced: .wav, .mp3 beside it, a spectrogram, and a short report. Clearly distinguishes itself from siblings by naming project_write, render_report, fl_exec, fl_call, and fl_transport with their relationship to this 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?

Explicitly says when to call it (after project_write to check a piece) and gives a negative constraint: make no live call (fl_exec, fl_call, fl_transport) before the render stops running. It also explains the refusal condition for a user-started FL instance, leaving no ambiguity about prerequisites.

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: nothing is written to any file, FL is not launched, playback restarts from the beginning even when already playing, and the return value is {playing, mode}. Minor tension with idempotentHint=true since a repeated 'play' restarts playback, but the description discloses this rather than hiding it, so it informs the agent.

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 and its effect on files, and every sentence carries information. It is dense and semicolon-heavy, bordering on run-on, which slightly slows parsing but does not waste words.

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

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

With no output schema, the description supplies the return shape ({playing, mode}), the runtime prerequisite, the mode fallback behavior, and the handoff to fl_render for actual audio. Nothing an agent needs to call this 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%, yet the description still adds semantics the schema lacks: 'song' means arrangement, 'pattern' loops a single pattern, the pattern number is selected first, omitting mode preserves FL's current mode, and play always starts from the beginning. This is meaningful enrichment over bare enum-like strings.

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

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

States a specific verb pair (play/stop) and resource (the open project's transport in the running FL), and explicitly scopes it as non-file-changing. It also distinguishes itself from fl_render, which saves and closes FL, so an agent can separate it from the nearest sibling.

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 preconditions (FL must already be open with a project; use project_write(open=true) otherwise) and names the alternative for audio capture (fl_render). It does not state when *not* to use it in favor of fl_probe or fl_call, but the routing guidance it does give is strong.

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), and the description adds beyond them: it only answers for plugins with a parameter map (a real coverage limitation) and that it 'reads files only; FL need not run', telling the agent it works without a live session.

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 meaning, then routing and caveats. Dense but every sentence carries information; the long nested automation-target parenthetical is the only heavy patch.

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 must explain returns — and it does: index usable as an automation target, name, and the normalised-value display at 0/.25/.5/.75/1 so a value can be chosen for a target Hz, dB or %. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents 'kind' (instrument/effect disambiguation), 'query' (case-insensitive all-words match), and 'plugin' (name from plugins). The description adds little parameter-level detail beyond implying that names are matched against the plugin's list; baseline 3 is appropriate.

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

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

States a specific verb+resource: it returns a plugin's automatable parameters, each with its index, name, and what its normalised value means. It explicitly distinguishes itself from 'plugins' (lists what's installed), 'presets' (a plugin's presets), and fl_call('plugins.getParamName', ...) for plugins without a parameter map.

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 ('Call it before automating a plugin or effect knob') and explicit non-uses ('Not for choosing a sound: plugins lists what is installed, presets a plugin's presets'), plus the fallback route for plugins lacking a parameter map.

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 a safe read-only operation, but the description adds substantial behavior: file-only reads, no running FL instance needed, default filtering behavior, format deduplication rules, and the exact row fields returned.

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?

Despite its length, the description is front-loaded with the core purpose and every sentence carries useful information about return fields, filtering, deduplication, or project_write integration. There is no redundant 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 documenting the returned row fields and how names map into project_write. Combined with annotations and full schema coverage, an agent has enough context 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 description coverage is 100%, so the parameter meanings are fully documented in the schema. The description repeats the native behavior but adds no new semantics for query, making the baseline 3 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: list the plugins this machine has, covering both FL's plugin database and tuned library instances. It clearly distinguishes itself from siblings like presets and params while also explaining how results feed into project_write.

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 call it before project_write to choose instruments and effects, and directs the agent to presets or params for plugin subresources. It also explains the default VST3/CLAP-only listing and the native=true override.

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: discloses the return shape, that total counts all matches, that limit produces an even spread per preset folder rather than a truncated prefix, the {ok:false, error} result for ambiguous/unknown plugin names, and that harvest opens the plugin in FL at ~1s per preset. This also explains why readOnlyHint=false despite the otherwise file-only read.

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 caller order come first, then return shape, then paging semantics, then failure mode, then the harvest caveat. Dense but every sentence carries information an agent would otherwise have to discover by error.

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

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

With no output schema, the description supplies both the success payload keys and the error payload, states the FL-runtime caveat for harvest, and covers the ambiguous-plugin failure. Nothing needed to call this 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 still adds value by explaining what the returned id is consumed by and how a plugin name that matches several plugins fails with named candidates. Parameter-level details (kind, query, limit) are 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?

Specific verb + resource (list presets for one plugin) plus the downstream consumer ('an id goes into project_write as an instrument's or effect's preset'), which tells an agent exactly what the output is for. It also names the ordering dependency on the 'plugins' sibling, so it is clearly distinguishable from others in the set.

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?

'Call it after plugins, when choosing a sound' gives an explicit sequencing rule and trigger condition, and the harvest note says when the harvest variant applies (presets living inside the plugin, not on disk). No explicit when-not or comparison to the adjacent 'samples' sibling is given, which keeps it 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?

Adds substantial context beyond annotations: reads subfolders recursively, FL need not be running, ~2s for 80 projects, writes profile.md/profile.json to tmp/profile, failed reads are listed not fatal, and the {ok: false, error} shape for an empty folder. The readOnlyHint=false annotation is consistent (the tool writes report files while changing no .flp), and the description clarifies this distinction.

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 what it does and returns before the fallback logic, and every clause carries information. It is a dense, semicolon-heavy run-on paragraph, costing a little readability, but little is wasted.

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

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

With no output schema, the description fully carries the return burden: it lists per-project fields, the error shape, the on-disk artifacts, and the config resolution behavior. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the folder parameter is already documented, so the schema carries the base meaning. The description adds value beyond it by explaining the full default chain (config projects_folder, then ask-and-persist), which the schema only gestures at with 'omit to use config projects_folder'.

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 ('List a person's projects from a folder of their .flp files') and enumerates the returned fields (tempo, key, arrangement length in bars). It explicitly distinguishes itself from the sibling project_read ('which to open and read in full with project_read').

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 positions itself as the lightweight triage step before project_read, and gives detailed fallback guidance: omit folder to use config projects_folder, ask the user and save it when unset, and set projects_folder to 'none' when the user has none. When and when-not are both covered.

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 past them: it states the file is unchanged, warns that 'full' is large and should be narrowed with patterns or arrangements, and discloses the failure mode ('the parser's error on a file that is not an .flp').

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 and the not-running/not-modified guarantees before any detail. It is long, and the view catalogue is dense, but nearly every clause carries decision-relevant information; only the inline tuple formats are slightly heavy for a description.

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 six parameters, no output schema, and four view modes, the description supplies exactly what is missing: the return shape per view, the default, the sizing caveat for 'full', and the error behavior. An agent can pick a view and call it correctly without opening 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 coverage is 100% and already documents bars, patterns and arrangements, so the schema carries the basics. The description still adds real value by explaining what each view returns and in what shape (note and clip row formats, per-bar sounding parts, score layout) and by naming 'compact' as default and 'summary' as the starting 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 ('Read one FL Studio .flp file into JSON') plus two crucial scope facts: FL need not be running and the file is not modified. It explicitly distinguishes itself from siblings profile and fl_exec by naming what those cover instead.

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 use cases ('see what a project holds', 'take parts from it', 'check what project_write wrote') and names the alternatives with the condition that selects them: profile for style across many projects, fl_exec for the project open in FL right now. 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 destructiveHint=true and idempotentHint=true, but the description adds genuine operational detail beyond them: the file at path is replaced, FL need not be running unless open/play is used, and FL first saves its currently open project before opening this one. The side-effect chain (launch FL, save existing project) is disclosed, which annotations alone do not 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 purpose and the destruction semantics, then organized into scannable sections (sounds, units, behavior, returns). Dense but each block is functional; the units section is arguably long but directly prevents common errors.

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 tool with no output schema and nested input, the description covers return values ('the file read back... and the writer's warnings; read them'), input format and reference material, unit conventions, and open/play side effects. An agent has what it needs to construct a document and predict consequences.

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

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

Schema coverage is 100%, so baseline is 3, but the description meaningfully elaborates the complex nested doc parameter: compact vs full form, the 'sounds' shapes (instrument as plugin+preset, effect as mixer.effects or copied form). It also warns about easy-to-mistake units. This adds real value over the schema's terse 'compact or full' note.

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: 'Write a project document to an .flp file, replacing any file at path.' This makes clear it is the write counterpart to project_read, and the follow-up 'This is how a piece gets made' frames the outcome an agent 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?

Given clear workflow context: 'Read one before a first write' points the agent to the README/example reference, and 'Without open, FL need not run' contrasts the open/play variants. It stops short of explicitly routing to sibling tools (e.g. project_read) by name, so 4 rather than 5.

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

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

Goes well beyond the annotations: it discloses non-blocking behavior ("it does not wait... while the render is still going it says so: call again"), the failure path (a failed render returns its log), and concrete side effects ("writes into tmp/spectro/ only" — a resized picture plus regenerated spectrogram and .txt). These are consistent with readOnlyHint=false, idempotentHint=true and destructiveHint=false, and add real operational context.

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-dense but written as a semicolon-chained run-on with oblique phrasing ("it answers to call fl_render first"), which forces re-reading. The most important fact — that it reads rather than renders — is front-loaded, but the middle clauses bury the polling instruction and side-effect notes.

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 no output schema, the description covers the return shape ([text, image]), what the text contains, the in-progress case, the failure case, the no-prerequisite case, and the on-disk side effects. An agent has everything needed to call it correctly and interpret its 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% and the schema already explains that only the file name is used to locate the render, including the same-name collision caveat. The prose only echoes this indirectly ("the .wav beside it"), so it adds little meaning beyond the structured field — 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 — read what fl_render produced — and enumerates the two return artifacts (short report text and spectrogram image) as [text, image]. It is explicitly positioned against the sibling fl_render that generates the output, so an agent can tell the producer from the reader 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 explicit ordering ("Call it after fl_render"), an alternative when the precondition is unmet ("With no render on record it answers to call fl_render first"), and downstream workflow guidance ("Look at the picture before handing a piece over"). It also states that FL need not be running, removing a common source of mis-invocation.

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, and the description reconciles that by stating 'Changes no sample file' while disclosing the actual writes: folder-listing cache in tmp/samples/index/ and a TSV when measure is set. It also documents the failure shape {ok: false, error} and that FL need not be running — context the annotations cannot express. Return-record format and truncation behavior are covered too, leaving only minor gaps like cache invalidation timing.

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?

Core purpose and the project_write handoff are front-loaded, and the paragraph breaks map to distinct modes (default, filtered, error, side effects). It is denser than it needs to be in places — semicolon-chained clauses and the tmp/ path details could be tightened — but no sentence is pure 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 7-parameter, all-optional tool with no output schema, the description supplies the return shape ({total, results: {folder: [[name, seconds]]}}), the error shape, truncation policy, and side effects. An agent has everything needed to call it 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 100%, so the schema baseline already carries per-parameter meaning. The description nonetheless adds non-obvious semantics the schema omits: that the no-argument form lists all sample folders with subfolder counts, that a query stays confined inside a supplied folder, and that past limit the results are an even spread across folders rather than a truncated head.

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 ('List samples for drums, one-shots, loops and breaks') and immediately connects its output to a sibling ('a sample's path ... goes into project_write'). An agent can distinguish it from presets, plugins, and project_read 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 sequencing ('Call it before choosing any sample'), an explicit constraint ('take samples only from folders the user gave'), and a documented recovery path when config sample_folders is unset (ask the user, then set it with config, or 'none' for factory packs). It names the alternative tool and the condition that selects it.

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