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

Beyond the annotations (which only say non-read-only, non-idempotent, open-world), it discloses the substantive behavior: each edit becomes a commit in the person's name, it auto-deploys once the theme validates, and the answer returns `live` or `held` with the errors to fix, build polling via `get_build`, and the file's warnings. It also adds the admin-only permission gate — exactly the context annotations cannot convey.

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?

Nearly every clause carries real information, but the delivery is a single tangled run-on ('goes live by itself once the theme is whole — no validator error, and in a theme that builds, built') that forces re-reading. The publish/safety semantics are buried mid-sentence rather than front-loaded.

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 live-publishing mutation with no output schema, it covers the important pieces: commit semantics, the two return states, remediation via `get_build`, a verification step, and the admin requirement. Remaining gaps are the failure mode when `find` matches zero or multiple times, and whether a published edit can be rolled back.

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?

With only 20% schema description coverage, the description must carry parameter meaning. It explains `find` and `replace` well (exact single match, whitespace-sensitive) and ties `site` to the supplied context, but leaves `path` and `theme` format/identity undocumented — the agent gets no hint whether the path is relative, includes the extension, or how the theme is named.

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 ('One change to a file of the theme') and precisely defines the edit mechanic (exact single match on `find`, whitespace included, substituted by `replace`). It does not, however, distinguish itself from the sibling `write_theme_file` or `delete_theme_file`, so the agent must infer the boundary between partial edit and whole-file write.

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 explicit alternatives and follow-ups: menu links belong to `set_navigation` and are 'never a link in the theme,' then `render_page` to verify, and access is restricted to admins. What it omits is guidance on when to use this instead of `write_theme_file` or `create_theme`, the closest overlapping siblings.

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