setSiteTimeZone

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

With no annotations provided, the description carries the full behavioral burden. It goes beyond a simple mutation statement by warning that timezone alone does not enable DST, explaining that DST is a separate disabled site setting, and describing the wall-clock impact on schedules. This is valuable, concrete behavioral disclosure.

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 stated in one direct sentence, followed by a relevant warning that earns its length. The DST explanation is verbose but necessary for correct usage. No filler or repetition.

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 simple setter with no output schema, the description covers the most important operational risk (DST behavior) and directs the agent to verification steps. It is not fully complete because siteId semantics remain unclear and there is no mention of expected response or result handling, but it is strong for a tool of this complexity.

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 schema already documents timeZone with an IANA example, and the description reinforces its meaning by warning that it does not affect DST. It also hints that region/scenario fields are handled internally. However, siteId is left completely undocumented, and at 50% schema coverage the description does not fully resolve parameter ambiguity.

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?

Starts with a specific verb and resource: 'Set the site timezone.' It also clarifies the tool's distinct role by noting it 'handles the region and scenario fields the controller requires alongside it,' which helps differentiate it from generic updateSiteSettings. No ambiguity about what operation is performed.

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?

Provides actionable guidance: after setting the timezone, check site.dst via getSiteSettings and use the schedule's notInDst flag as confirmation. It also states the authentication requirement. It does not explicitly enumerate when to avoid the tool, but the context is clear enough for selection.

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