Write a theme file

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical behaviors: it 'Refuses to write to a live active theme by default' unless allow_live_theme is set, and 'PHP is syntax-checked before it is saved, so a parse error is reported rather than fataling the site.' These are safety and error-handling traits not present in the schema or annotations, giving the agent essential operational knowledge.

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?

Two sentences, with the core action and overwrite semantics front-loaded in the first sentence. The second sentence packs two important safety behaviors (draft requirement and syntax check) without waste. Every clause serves a purpose, making it efficient and scannable.

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 a potentially destructive write operation, the description covers the key safety context: drafting is encouraged, live writes are guarded, and syntax errors are handled gracefully. The parameter schema handles the rest. It does not mention return values (no output schema) or permission requirements, but these are not explicitly needed given the schema and annotations. The description is sufficiently complete for correct invocation, with a slight omission of what happens on success, though output schema absence makes that less critical.

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 coverage is 100%, so all parameters are already documented. The description adds minimal parameter-specific insight beyond restating the overwrite semantics; for example, it reinforces the default draft behavior but does not explain syntax or format of path or content beyond the schema. Since the schema already explains the parameters, the description provides only marginal added value, aligning with the baseline of 3.

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 ('Create or overwrite') and resource ('a theme file') with a clear scope ('replacing its entire contents'). It distinguishes from siblings like read_theme_file, edit_theme_file, and delete_theme_file by the overwrite action and the draft-workflow emphasis. The phrase 'Refuses to write to a live active theme by default' further defines its boundary.

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 clearly advises working in a draft ('work in a draft (create_draft_theme) so the site stays untouched until you publish') and warns against live writes (via allow_live_theme). It names the sibling create_draft_theme and contrasts with the default refusal, but does not explicitly mention alternative write tools like edit_theme_file for partial changes. This gives strong context but lacks an explicit 'when not to use this' statement for partial edits.

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