get_weather_by_name

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

No annotations provided, so description carries full burden. It discloses geocoding cascade (Amap → Photon → Nominatim) and weather data aggregation with fallback to open-meteo without API key. Good transparency, but lacks details on rate limits or real-time behavior.

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?

Well-structured: starts with purpose, then geocoding details, Chinese tips, and parameter descriptions. Somewhat lengthy but each sentence adds value. Minor redundancy in Chinese text could be trimmed.

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?

Covers key aspects: purpose, geocoding, provider options, and return keys. However, return values are only listed as keys without types or examples; no output schema. Could explain what 'all' provider includes and the structure of _meta. Given complexity, slight gaps.

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 has 0% coverage; description adds full meaning: explains place_name should use full administrative divisions for Chinese, and provider lists valid options (all, qweather, open-meteo, wttr). Adds significant value beyond 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?

Description explicitly states the tool gets comprehensive weather by place name (current + hourly + daily). Distinct from sibling get_weather_by_position by advising use of that tool for precise location. Clear and specific.

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 clear context on when to use this tool vs get_weather_by_position, and gives tips for Chinese place names (use full administrative divisions). No explicit when-not to use, but alternative is mentioned.

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