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?

Annotations only give destructiveHint=true/readOnlyHint=false, but the description adds the critical nuance that a setter edits the open project in memory 'as an edit by hand would; nothing is saved' — i.e. changes are transient and never written to the .flp. It also discloses that FL is launched if needed and that the tool is Windows/FL Studio only, which are real preconditions not present in 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-loads the action and return shape, then routes to alternatives, then discloses side-effect/launch/platform semantics. Every clause carries information; nothing is filler despite the fairly dense prose.

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 ({ok, value} or {ok: false, error}). Combined with persistence semantics, launch behavior and platform limits, an agent has everything needed to invoke it safely.

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 both parameters (fn, args) are documented with format examples in the schema, so the baseline is 3. The description adds no extra syntax or constraint detail beyond what the schema already states about 'module.function' and positional args.

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: 'Call one function of FL's scripting API inside the running FL and return what it returns', with the exact return shape ({ok, value} / {ok: false, error}). It distinguishes itself from siblings fl_exec, project_read and project_write by scope, so an agent can pick correctly 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 when-to-use ('For a single read or change, e.g. a parameter name or a mixer level') and explicit alternatives for other cases ('Use fl_exec for several calls or logic; use project_read and project_write for anything the .flp file holds, which need no FL'). No inference required.

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: the sandbox refuses files/sockets/pipes, changes act only on the open project and are not saved, FL may be launched on demand, and the return shape is {ok, value} or {ok: false, error} with traceback. This is substantial extra context over the destructiveHint/openWorldHint flags.

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 dense sentences, front-loaded with the core action and the fl_call disambiguation early. Slightly packed with environment caveats, but each sentence carries load.

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, yet the description explains both success and failure return shapes, the `result` contract, sandbox limits, persistence behavior and platform requirements. Nothing an agent needs to invoke 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 description coverage is 100%, so the schema already documents code, out and timeout. The description reinforces the `result` assignment convention and the __out__ path convention, but adds no syntax or format detail the schema lacks. 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+resource: 'Run Python inside the running FL's embedded interpreter', with the module namespace (channels, mixer, plugins, transport, patterns) spelled out. It explicitly differentiates from the sibling fl_call ('one call is simpler with fl_call'), so an agent can route 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 the selecting condition ('live reads or changes that need several calls or logic') and names the alternative (fl_call) for the simpler case. It also adds environment gates: Windows with FL Studio only, and it will launch FL if 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 already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, but the description goes well beyond them: it names what is overwritten (an older copy of the controller script), where state lives (the registry, which FL rewrites on close), the failure mode when FL is open, and the exact return keys {ok, installed, bridge, changed, midi, next}. This is unusually rich 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?

Front-loaded with the essential trigger and prerequisite, and every sentence carries operational information. It is dense and somewhat run-on in the two enumerated steps, but nothing is padding, so it stays efficient without being maximal.

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 listing the return shape, and it covers prerequisites, platform scope, side effects, and the next step in the workflow. An agent has everything needed to decide whether and when to call 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description mentions a config key (fl_hardware) that the call writes, which is contextual rather than argument-related, and there is nothing further to document.

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 ('Set up the live link to FL') and then enumerates the two concrete actions it performs, so an agent knows exactly what happens without opening anything. It is clearly distinguishable from siblings like fl_probe, fl_call, and fl_exec, which are referenced as downstream steps rather than substitutes.

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 trigger conditions ('needed once per install, and again after this folder moves'), a prerequisite ('Close FL first'), a platform constraint ('Windows with FL Studio only'), and the follow-up action ('start FL and call fl_probe'). It even names the conditional case where the MIDI port step is skipped.

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

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

It goes well beyond the annotations by disclosing the real side effect (launches loopMIDI and FL when they are not running, with launched_fl_seconds reporting FL's startup time), which explains why readOnlyHint=false despite the tool not touching the project. It also promises a self-describing error rather than a silent failure. It stops short of covering timeouts, blocking duration, or what happens if a launch fails, which is why it is not a 5.

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

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

Front-loaded with the return values an agent needs to interpret the result, then the invocation triggers, then the side effects and platform caveats. Every clause carries information; nothing is redundant with 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?

For a zero-parameter, no-output-schema diagnostic whose behavior is environment-dependent, the description covers returns, side effects, triggers, and platform limits. Minor gaps remain around how long the call may block when it has to launch FL, or what the error states look like beyond 'an error saying what 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies a no-argument call and adds no confusing parameter talk.

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 operation (probe the live FL link) and enumerates exactly what it returns: FL's scripting API version, embedded Python version, pid, pipe handle, or a descriptive error. It is immediately distinguishable from siblings like fl_exec, fl_call, and fl_transport, which act on the link rather than diagnose 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 gives explicit triggers: call it first when a live tool (fl_exec, fl_call, fl_transport, project_write with open) fails, and after fl_install. It also names the platform precondition (Windows with FL Studio only) and states it reads nothing from the project, implicitly excluding it from data-retrieval workflows.

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 critical operational context: it replaces earlier outputs, saves the open FL project first, restores the path if saving overwrote it, closes FL, runs detached, and returns a log file. It also gives timing expectations and platform limits.

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 render outcome, then usage, side effects, return behavior, timing, and platform constraints. Every sentence carries necessary operational information with no filler.

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

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

For a complex, destructive, detached render tool with no output schema, the description explains what the call returns at once, how to read results via the log file, what files are produced, and key side effects. Nothing essential for correct invocation appears missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the input schema, including the key examples and the reopen default. The description does not add syntax or format details beyond what the schema provides, so the baseline of 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 and resource: render an .flp to audio, producing .wav, .mp3, spectrogram, and stereo statistics. This distinguishes it from sibling tools like project_write, project_read, and fl_transport without requiring schema inspection.

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 after project_write to check a piece, and notes Windows with FL Studio only. It gives clear context and a prerequisite, though it does not name when-not to use it versus alternatives such as fl_transport.

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: play always jumps to the start rather than resuming, playback restarts if re-invoked, no file is modified, FL is launched if absent but with nothing open, and the return value is {playing, mode}. It also states the platform constraint (Windows with FL Studio only). This is consistent with destructiveHint=false and 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?

The core action is front-loaded in the first clause, and no sentence is filler. It is a dense single paragraph with heavy parenthetical nesting, which slightly hurts scanability for an agent extracting the play/stop contract.

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

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

There is no output schema, but the description supplies the return shape ({playing, mode}) plus the launch-state caveat and the cross-tool handoffs needed to actually get results. 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%, so the baseline is 3, but the description adds real meaning: 'song' plays the arrangement, 'pattern' loops a single pattern which must be selected first, and omitting mode preserves FL's existing setting. The mode/pattern interaction is documented better here than in the schema alone.

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) over a specific resource (the project open in the running FL) and immediately scopes it: 'it changes nothing in any file.' It also distinguishes itself from siblings by name, pointing to fl_render for audio output and project_write for opening a project.

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 covers when each action applies, what 'play' does when already playing (restarts from start), how mode interacts with pattern, and what happens when FL is not running. It names the alternatives and the exact conditions that select them (project_write(open=true), play='song'; fl_render to save and close).

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/false openWorld, so safety is covered. The description adds genuine behavior the annotations cannot: 'Reads files only; FL need not run' and the constraint that it only answers for plugins that have a parameter map. Return semantics for normalised values are also disclosed. No rate-limit or pagination notes, but those are likely N/A.

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 in the first clause, then routing and caveats. Dense but nearly every clause carries information. The stacked parenthetical about automation-target shapes is the one spot that reads as cramped rather than crisp.

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 exactly what is returned (index, name, normalised value with FL's display at 0/.25/.5/.75/1 so a value can be chosen for a target Hz/dB/%). Combined with the routing guidance and the file-read-only note, an agent has everything needed to call and interpret 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%, so both inputs (plugin, query) are fully documented in the schema and the description adds no input-format detail beyond it. The description's index/automation-target explanation ('{channel: id, param: index}') describes returned data and usage, not the input parameters, 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 resource and scope: a plugin's automatable parameters, with each one's index, name, and normalised value meaning. It explicitly distinguishes itself from siblings 'plugins' (what is installed) and 'presets' (a plugin's presets), and names the fallback 'fl_call plugins.getParamName' for plugins lacking 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 explicit timing ('Call it before automating a plugin or effect knob'), explicit exclusions ('Not for choosing a sound'), and named alternatives ('plugins lists what is installed, presets a plugin's presets'). The condition under which the tool does NOT answer, and the workaround, are both stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value beyond them: 'Reads files only; FL need not run' discloses that no host session is required, and it explains format-resolution precedence (native, then vst3, clap, vst) and what happens when no preset is given. It stops short of covering pagination or query behavior, but the read/write profile is fully clear.

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, and the row-shape and project_write payload syntax are genuinely useful. It is dense, with several long run-on sentences that pack multiple facts per clause, 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 takes on the burden of describing returns and does so: it enumerates each row's fields (name, kind, vendor, format, source, preset count, parameter map) and explains how a listing entry maps into project_write arguments. An agent has everything needed to call it and use 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?

There is a single optional query parameter whose schema description is 100% covered, so the schema already carries its meaning. The description adds no syntax or filtering detail beyond implying a general listing, 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?

States a specific verb and resource ('List the plugins this machine has') and scopes it precisely (FL plugin database plus tuned library instances). It is clearly distinguishable from siblings presets and params, which it names as separate concerns.

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 ('to choose instruments and effects before project_write') and routes the agent onward to presets for a plugin's presets and params for automatable parameters. Nothing about selection 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?

Beyond the readOnly/idempotent annotations, the description discloses the return shape ({plugin, kind, total, presets}), that total counts every match even when limit truncates the list, the ambiguous-match error behavior ({ok: false, error} naming candidates), and that it only reads files (FL need not run). This is rich context that annotations alone would 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?

The description is dense and front-loads purpose, then workflow, then return/error behavior. Every sentence carries information, though the single run-on style is slightly heavy; nothing is 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 fully compensates by describing the return shape, the total/limit relationship, and the error case. Combined with 100% parameter coverage, 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% so the baseline is 3, but the description adds meaning: 'catalog order' ordering and the fact that total counts all matches even when limit cuts the list, which clarifies the limit parameter's semantics. The plugin matching behavior (unique part, ambiguous -> error) is also elaborated.

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

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

States a specific verb (List) and resource (presets) scoped to one plugin, and clarifies that ids are returned in catalog order. An agent can distinguish it from siblings like plugins and params 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?

Explicit sequencing guidance: 'Call it after plugins, when choosing a sound.' It also routes the output forward, noting an id 'goes into project_write as an instrument's or effect's preset,' which tells the agent how this tool fits 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?

Goes well past the annotations: recursion into subfolders, no modification of the .flp files, FL need not be running, ~2 s for 80 projects, the write of profile.md/profile.json to tmp/profile/<folder name>/, non-fatal read failures, and the {ok: false, error} shape on an empty folder. This is exactly the extra context annotations cannot carry, and readOnlyHint=false is consistent with the tmp file writes.

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 sibling routing are front-loaded, and every sentence carries information (timing, output, error behavior). Some clauses are densely stacked in a single run-on sentence, which costs a little readability.

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

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

With one parameter, no output schema, and non-destructive annotations, the description still covers what is returned (tempo, key, arrangement length in bars), where artifacts are written, failure modes, and runtime. 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% and the folder parameter is already documented as absolute or repo-relative. The description still adds real semantics: recursion into subfolders and the fact that the folder name determines the output path under tmp/profile/.

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 a person's projects from a folder of their .flp files") and immediately distinguishes itself from the sibling that reads a single project's contents. An agent can tell profile apart from project_read 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?

Routes the agent explicitly to project_read for single-project contents and frames profile as the survey step that decides which projects to open in full. It gives clear context for use but states no exclusions beyond that routing (e.g. what to do if the folder is huge or already profiled).

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 baseline is covered. The description adds genuinely useful context beyond that: FL need not be running, the file is not changed, and the failure mode (parser error on a non-.flp). It stops short of describing pagination or cost of the 'large' full view in more detail, so a 4 rather than a 5.

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

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

Front-loaded with purpose and the routing sentence before the detailed view breakdown, and every sentence carries information. The dense view/row-format sentence is long but earns its place; nothing is redundant boilerplate.

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?

Though there is no output schema, the description spells out the three view shapes and the exact field layout of the default return, plus error behavior — everything an agent needs to interpret results and call correctly is present for a 5-parameter read 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 baseline is 3, but the description substantially enriches meaning beyond the terse schema: it defines what each view returns ('summary' contents, 'compact' row shape, 'full' byte-for-byte round-trip) and the notes/clips row layout including the src encoding (pattern id, s<N> sample, a<N> automation). It never mentions the 'unused', 'patterns', or 'arrangements' parameters, leaving that 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 ('Read one FL Studio .flp file into JSON') and immediately distinguishes itself from siblings by naming project_write (whose output it verifies), profile, and fl_exec. An agent can tell exactly what this does versus the other 12 tools 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 use cases ('see what a project holds, to take parts from it, or to check what project_write wrote') and routes alternatives by condition: profile for style across many projects, fl_exec for the project open in FL right now. This is textbook when-to-use/when-not 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 flag destructive=true and idempotent=true, but the description adds real behavioral context beyond them: the file at path is overwritten, FL may be launched, and with open/play FL first saves the currently-open project so no dialog appears. It also discloses that warnings are returned, which no annotation covers.

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 overwrite warning, then organized into document, sounds, units, and runtime sections. It is long, but nearly every line carries actionable detail, so it stays efficient rather than padded.

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 present, the description compensates by stating the return shape (channels, notes per pattern, clips per arrangement, plus writer's warnings) and advising the agent to read them. Combined with the units and sound-definition guidance, 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%, so the baseline is 3, but the description goes further by defining what 'doc' accepts (compact or full form), citing field references, and supplying hard domain units (96 ticks/beat, MIDI 60 = C4, 0.8 = 0 dB, tempo = (bpm-60)/120) that the schema does not encode.

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') plus the critical side effect ('replacing any file at path'), and clarifies it is the counterpart to project_read by describing the document it consumes. An agent can immediately distinguish it from project_read and the fl_* execution 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?

Gives concrete context: read a working example before the first write, and explains the runtime condition ('Without open, FL need not run'). It does not explicitly name project_read or other sibling tools as alternatives, so it stops just short of full when-to-use/when-not coverage.

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