learn_plugin_profile

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

Annotations already declare this is a non-read-only but non-destructive, closed-world write, and the description is consistent with that (it writes into a catalogue, refreshes existing entries). It adds real context beyond the annotations: the plug-in must actually be loaded and exposed in Live, and the result feeds later profile/control calls. It does not say whether an existing profile is overwritten wholesale or merged, nor whether Live must be in a particular state.

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?

Three tight sentences that front-load the action, then the fallback condition, then downstream consumers. The parenthetical plug-in list earns its place by making the fallback case recognizable; nothing is repeated.

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?

An output schema exists, so return values need no explanation, and the lifecycle context (offline scan fallback, refresh after Configure, consumed by get_plugin_profile/set_control/add_effect) is well covered. However, for a three-parameter write tool with zero schema description coverage, the total absence of parameter meaning leaves a real gap in what an agent needs 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 0%, so the description carries the full burden, yet it never mentions any of the three parameters. device_name is only obliquely implied by "a loaded plug-in," and track_index and track_type (default "track") are entirely unexplained — an agent must guess whether track_type expects "track", "return", or "master".

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 pairs a specific verb ("Record") with a specific resource ("the parameters a loaded plug-in exposes in Live") and a destination ("the catalogue"). It also distinguishes itself from the offline scanner path and names the sibling consumers (get_plugin_profile, set_control, add_effect), so an agent can tell it apart from scan_plugin_catalog or expose_plugin_params without opening schemas.

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 a clear trigger: use it as the fallback when the offline scanner cannot load a plug-in, or to refresh what Live exposes after Configure. Named examples (Keyscape, Pianoteq, LABS, Serum 2, MODO BASS) make the fallback condition concrete. It stops short of an explicit "otherwise prefer scan_plugin_catalog" routing statement.

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