播放控制

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

The annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the description's job is to add context, and it does: it discloses that actions are sent as OS-level media keys, that they affect an external application the user controls, and that macOS requires an Accessibility grant on first use. It omits edge-case behavior such as failure when nothing is playing, and whether mute is a toggle, but that gap is minor.

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: the capability and its action list come first, the mechanism and target app second, and the setup prerequisite last. Each clause earns its place. The parenthetical NetEase Cloud Music example is illustrative but slightly wordy.

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 only two fully documented parameters, no output schema, and annotations covering the safety profile, the description covers the essentials: what it controls, how, on which app, and the macOS permission gate. What is missing is only the failure mode when no media session exists and whether mute reflects or toggles state.

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%: the action enum has per-value Chinese glosses and times documents the repeat count and its 1–10 bounds. The description adds nothing about times, even though it could explain that times only matters for the volume actions; it also does not say whether volume_up adjusts system volume or per-app volume. With the schema fully documented, the baseline 3 is correct.

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 specific verb and resource and enumerates the six supported actions (play/pause, previous, next, volume, mute). It also explains the mechanism (system media keys) and the target scope (whichever app is currently playing). It never names the closest sibling, play_in_app, so the agent must infer the distinction between system-level media keys and in-app playback.

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?

Usage is implied by the scoping sentence: the tool controls whatever app is currently playing, whereas an in-app tool would control the app itself. The description also gives a macOS Accessibility prerequisite. However, it never explicitly says when to prefer this tool over play_in_app, or what happens when no media app is active, leaving the agent to infer.

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