Retrieve the active take index for a media item on a REAPER track. Use it to identify which take is active or detect items with no active take (-1).
Get the index of the active take of a media item.
Returns: Object with 'ret' = active take index (-1 if the item has no active take).
| Name | Required | Description | Default |
|---|---|---|---|
| item_index | Yes | ||
| track_index | Yes |
Changes observed during successful MCP inspections.
v1.7.3Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already declaring this as a safe read, the description goes further by defining the return shape and the sentinel value -1 for 'no active take', which is genuinely useful behavioral context an agent can act on. It stops short of describing what happens on an invalid track/item index.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight lines: the purpose sentence front-loads the verb and resource, and the Returns block cleanly scopes the output. 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?
There is no output schema, so the description rightly carries the return contract, and the -1 sentinel makes it callable without ambiguity. The remaining gap is that the two required indexing parameters are undescribed, leaving callers to guess how to address a valid item.
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 0% and the description adds nothing about track_index or item_index beyond implying they locate a media item. With two undocumented required integer parameters, the agent gets no help interpreting indexing base, valid ranges, or whether indices refer to the currently selected track.
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 precise verb (Get) and resource (the index of the active take of a media item), and its return specification (-1 when no active take exists) cleanly separates it from siblings like get_takes, which lists takes, and set_active_take, which mutates.
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?
Reading the description makes it obvious this is the read counterpart to set_active_take, but there is no explicit 'use this when... vs set_active_take/get_takes when...' guidance or mention of a prerequisite that an item must be selected or exist. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.