unit_mission

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

With no annotations, the description carries the full burden and does so well: it discloses that air strikes return an `attack` payload with both sides' hp and interceptor/shot_down fields, that effects report followers/influence before-and-after, that great_work names the work, that automation sets automated=true and lists the unit under turn_status.todo.ongoing, and that a conditional order is paused on reassignment. It stops short of stating permissions, failure modes, or validation errors.

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 content is information-dense and mostly earns its place, but it is delivered as a single sprawling block of run-on sentences with no headings or bullet structure, making it harder to scan than it needs to be for the amount of material covered.

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 annotations, no output schema, and 0% schema coverage, the description is impressively complete, covering mission semantics, return payloads, and side effects. Remaining gaps are minor (error conditions, parameter defaults).

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 coverage is 0%, so the description must compensate, and it does: it explains that x/y are for movement-shaped missions, that MISSION_BUILD uses `build` rather than x/y, and it enumerates valid mission values. The unit_id and the default -1 sentinel values are left implicit, keeping it from a 5.

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 (give a mission) and resource (a unit), then enumerates the mission values so the agent knows the exact scope. It also distinguishes itself from move_unit and give_order by describing how missions interact with those tools.

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 concrete when-to-use guidance for several missions (e.g. SPREAD_RELIGION requires the unit inside or adjacent to the target city; MISSION_BUILD takes the improvement in `build`, not x/y; automation buttons are usable when available_unit_actions lists them). It references siblings like available_unit_actions and give_order but never states a general 'use this instead of X' rule.

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