gift_tile_improvement_options

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

With no annotations, the description carries the full burden and does well: it discloses that gifting requires an alliance and sufficient gold, that plots are limited to tiles within search_radius of the capital where the gift is legal, that unrevealed tiles come back as bare coordinates, and that empty plots with can=true means nothing left to improve.

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?

Front-loads the identity of the tool (the button and its hexes) before enumerating the output fields, and each sentence carries information. Slightly dense with backtick-heavy field naming, but nothing is wasted.

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?

No output schema and no annotations exist, so the description must describe the return shape — and it does, covering can/cost/why_not/plots and the edge case of empty plots. Input side (player_id) is the only under-covered piece.

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?

One parameter (player_id) with 0% schema description coverage, so the description must compensate — it doesn't explain player_id at all, though the name is largely self-explanatory. Its detail is spent on output fields rather than input semantics, so baseline 3 is fair.

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 resource (the city-state screen's 'Gift Improvement' button) and what the call returns (the button state plus the hexes it would highlight). It reads as a preview/options query, which is distinguishable from the sibling action tool gift_tile_improvement, though that sibling is never named explicitly.

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 — you call this to inspect gifting options before committing via gift_tile_improvement — but the description never states when to use this versus the action tool, nor any prerequisites or ordering.

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