weather_update_location

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

Descriptions go beyond the destructiveHint=true annotation by explaining exact mutation semantics: omitted fields remain unchanged, additional_aliases replaces rather than appends, [] removes them, and make_default=true selects the default. It also transparently states that ambiguous geocoding returns candidates without saving and requires retry with candidate_id, which is valuable behavioral context.

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?

Every sentence adds operational value and there is no filler. The description is front-loaded with the core purpose, then systematically explains parameter effects and the ambiguous-geocoding flow in a compact, readable structure.

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?

Given no output schema and seven parameters, the description explains most key behaviors including candidate resolution, alias replacement/removal, and default placement. The only notable omission is country_code, and it does not spell out when to choose this tool over siblings, but overall the operational behavior is well covered.

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 burden of explaining parameters. It covers alias, place_name, new_alias, additional_aliases, make_default, and candidate_id with meaningful usage context. However, country_code is entirely unexplained despite having a default value, leaving a small gap.

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?

Description states a specific verb ('Update') and resource ('an existing location'), and explicitly distinguishes this from adding a slot. It names key sub-behaviors (place_name geocoding, aliases, default selection) so an agent can distinguish it from siblings like weather_set_location and weather_remove_location.

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 phrase 'without adding a slot' implies this tool is for modifying an existing location rather than creating one, but it never explicitly says 'use this when the location already exists' or names alternatives such as weather_set_location for creation. The intended use is inferable but not directly stated.

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