sb_theme

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description explains the tool operates in two modes: read-only when empty, and patch when colors/text_styles are supplied. It also discloses that unmentioned fields are preserved, which is valuable behavioral context. It does not contradict the annotations, since PATCH is consistent with readOnlyHint=false and 'kept' fields align with destructiveHint=false.

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 whole description is two sentences that pack the core function, the read/patch duality, and the merge behavior without repetition. The cause-effect phrasing 'so one token repaints every page at once' is concise and adds the key consequence. No wasted or unrelated information.

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?

The description tells an agent how to read and how to patch safely, and the merge behavior is well communicated. But it omits what dry_run actually does, what site_id refers to, and what the result of the operation looks like. With 4 parameters and no output schema, these missing pieces keep the description from being fully complete.

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?

The description adds meaning to colors and text_styles by tying them to the PATCH operation and merge semantics. However, dry_run and site_id are not described in either the schema parameter descriptions or this prose, and at 50% schema coverage the description needs to compensate for those gaps. It fails to do so, leaving the agent to guess at those two parameters.

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 identifies the resource ('the site's palette and type scale') and the actions ('read' / 'PATCH'), which clearly differentiates this from page, media, and publish tools. It does not explicitly name sibling tools for disambiguation, so it stops short of full sibling differentiation.

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?

The description gives explicit invocation guidance: call with no arguments to read the current theme, and call with colors/text_styles to update (PATCH) the saved document. It also explains the partial-update behavior ('what you do not name is kept'). It does not compare against other tools or provide when-not-to-use scenarios, but the intended usage branches are clear.

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