Load or recast an executor configuration

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

With no annotations supplied, the description carries the full burden and does so unusually well: it discloses refusals (missing targets, locks), that preview:true sends nothing, that selection/programmer/faders/trigger playback are untouched and stored custom commands are not executed, that mutations are serialised only within this server while other clients can change references, that uncertain commands are never retried, and that returned functions are observations rather than verification of a saved profile. It also explains the verification approach (read-back of identity, unchanged assigned object, expected dimensions) and why saving profiles is unsupported.

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 purpose is front-loaded in the first sentence and every subsequent sentence conveys a distinct safety or planning fact. It is dense to the point of being hard to parse in one pass, and the closing note about Store Page At Configuration is an aside that could be trimmed, but the content is not padding.

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 an 8-parameter, mutation-capable tool with no annotations and no output schema, the description covers mode selection, planning, locking, side effects, serialisation and verification scope. The remaining gap is that it never describes the shape of a successful response or what a plan result looks like, which matters since no output schema exists.

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 only 13%, so the description must compensate, and it largely does: it ties page/executor to the Assign syntax, configuration to <n>, apply to committing a recast, preview to sending nothing, data_pool to the pool scan, and executors to the exact {data_pool,page,executor} match requirement. It adds the constraint (must match the fresh affected list) that the schema cannot express, though it does not clarify units/ranges for page, executor or data_pool beyond what the schema has.

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 two concrete operations on a specific resource: load an existing Configuration onto an explicit page/executor, or recast its functions across all referencing executors, and gives the underlying command syntax (Assign Configuration <n> At Page <p>.<e> / Recast Configuration <n>). That is specific verb+resource, though 'recast' is domain jargon and the description never distinguishes this tool from nearby siblings such as gma3_assign_to_executor or gma3_configure_executor.

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

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

It gives clear conditions for each mode: load for a single explicit page/executor, recast for all referencing executors, with recast defaulting to a read-only plan that requires apply:true plus an executors list matching the fresh affected list. It also states prerequisites for failure cases (missing/unreadable targets and page/executor locks are refused, so unlock first). It stops short of naming an alternative sibling tool when this one is the wrong choice.

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