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

The description adds one genuinely non-obvious behavioral fact beyond the annotations: the variables are public and anyone can read them, which is a real warning against storing secrets. However, the annotations flag destructiveHint=true and the description never explains that consequence — whether the call replaces the entire variable set, whether omitted names are deleted, or what permissions are required.

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 short sentences, front-loaded with the action and immediately followed by the constraint that matters. No padding or redundant restatement of the title.

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?

This is a destructive, idempotent mutation with two required parameters, a union-typed payload, no output schema, and zero schema coverage — the description is too thin for that profile. It omits replace-versus-merge semantics, the meaning of slug, and the accepted variable forms, which are exactly what an agent needs before overwriting a site's configuration.

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 0%, so the description carries the full burden, and it only covers part of one parameter — the NAME placeholder hints at the variable name field. It says nothing about the required slug (which site) or about the dual shape of the variables argument (a name→value map versus an array of objects with name, label, and value), all of which are ambiguous in the schema.

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?

States a specific verb and resource ("Set a site's public variables") and even clarifies the mechanism with the {{ vars.NAME }} template reference, so the agent knows what the values become. It does not distinguish itself from sibling setters like set_links or set_password_protection, which is the only thing keeping it from a 5.

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 rather than stated: an agent can infer you call this when a site's templates need consistent values. There is no explicit when-to-use, no precondition (ownership or auth), and no mention of how this relates to update_site or edit_site.

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