fl_get_selected_range

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that it reads 'raw endpoints and PPQ' and does not 'claim meter or rendering semantics', which provides some context on the nature of data returned. However, it does not describe what the output looks like, any side effects (likely none given readOnly), or any limitations beyond the vague disclaimer. With annotations covering safety, the description offers limited additional behavioral insight.

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 one sentence with no filler. It front-loads the action ('Read') and a key detail (raw endpoints and PPQ). However, the phrasing is terse and uses jargon that may be unclear, but conciseness is positive.

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?

The tool has an output schema (not shown in detail) that could clarify return values, but the description still lacks clarity on what 'endpoints' and 'PPQ' mean, and no guidance on when to use it. Given the complexities of FL Studio concepts, the description is too vague to fully guide an agent on what to expect or how to interpret the result. It doesn't mention any prerequisites or connection to other tools.

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 has zero parameters)Skip; the description correctly adds no parameter semantics. Since there are no parameters to describe, the description does not need to compensate, but it also doesn't add value in this dimension. The baseline for 0 params is 4, but given that the description is vague about what the read returns, the parameter semantics dimension is moot; I'll rate 3 as neutral.

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 says 'Read raw endpoints and PPQ' which is specific about what is read, but it is not entirely clear what 'endpoints' and 'PPQ' refer to in the context of FL Studio. It mentions 'without claiming meter or rendering semantics', which hints at a distinction but the core purpose is somewhat ambiguous. It doesn't explicitly name the resource as a playlist selection, though the title is 'Get raw Playlist timeline selection', which is in annotations.

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 does not state when to use this tool or contrast it with alternatives. There is no mention of when to prefer this over other read tools like fl_get_project_summary or fl_get_transport_state. The vague phrasing 'without claiming meter or rendering semantics' implies it is for raw data, but it does not explicitly state the context in which this is the right choice.

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