screenstudio_brand

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

Annotations supply destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: it explains that apply is live and undoable, that save silently replaces existing brands, that delete is permanent even when a brand no longer reads, that caption contrast is validated against WCAG 4.5:1 with an automatic readable fallback box, that the cursor set is checked against the app, and that toPreset reports when the build cannot save presets. It also states what is mutated (settings in the open editor) and that it returns settings and reasons.

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 the action list is set off cleanly. It is dense and long, but for a six-action tool with a large nested brand object, most sentences earn their place; the enumeration of brand fields is long but load-bearing since the schema lacks descriptions.

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?

Given 7 parameters, a nested brand object, no output schema, and annotations that only flag the safety profile, the description is largely complete — it covers each action's behavior, validation checks, limitations, and even return semantics ('returns the settings it changed and why'). The unexplained stepMs parameter and the action/parameter 'save' collision are the remaining gaps.

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?

Top-level schema description coverage is 0%, so the description carries the burden and does so well: it explains name, projectPath (which project apply/toPreset act on), show (suppress live preview unless false), and the entire nested brand object (colours, backdrop modes, captions, cursor, sound, radius, shadow, padding, voice, music). Two gaps remain — the stepMs parameter is never mentioned, and the boolean 'save' parameter is ambiguous against the action of the same name.

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 opening sentence states a specific verb+resource and scope: 'Save a client's brand once and apply it to any project as one live, undoable config op.' It further distinguishes this tool from siblings like screenstudio_presets and screenstudio_editor_apply by enumerating its six actions (save/list/show/delete/apply/toPreset). An agent can identify what this tool owns without opening the schema.

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?

Each action is described with its own trigger and behavior — save replaces a same-named brand, delete is permanent even for unreadable brands, toPreset asks the app to persist a Screen Studio preset. It notes the current limitation ('Image backdrops are not supported yet'). It does not explicitly name alternate sibling tools for overlapping work, so there is no hard when-not/alternative routing, but action-level guidance is strong.

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