build_structure

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 tier prices are quoted by a 402 and charged automatically, that only one build per tile is allowed at a time with a 429 refusal issued before any money moves, and that builds on different tiles run in parallel. It also flags castle as upgrade-only and walls as overlay-capable, giving the agent real behavioral expectations for a write operation.

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 purpose and the type enumeration are front-loaded, and most clauses carry load-bearing game mechanics. It is a single dense paragraph, though, and a few asides such as 'the score the table weighs' add rhetorical weight without new information.

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 complex mutation with no output schema and no annotations, the description covers types, upgrade semantics, pricing, concurrency, and placement restrictions thoroughly. The only real gap is that it does not describe what a successful call returns or confirm the auth expectation behind api_key.

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 100% so the baseline is 3, but the description goes beyond it by explaining the meaning and consequences of each building_type enum value (what market, barracks, watchtower, walls, and castle actually do), which is the decision-relevant semantics for the only non-obvious parameter. api_key and territory_id are left to the 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?

States a clear verb and resource ('Build or upgrade on your territory') and then enumerates exactly what each building type does, including the key distinction that market is the only type that moves dominion weight. However, it never addresses the sibling 'place_building', so an agent cannot tell from the description alone which of the two is the correct entry point for construction.

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?

Gives concrete usage rules: calling with an existing same-type building upgrades it one tier, castle is upgrade-only, one MAIN building per territory, and walls coexist with any building. It also frames the strategic choice ('walling your castle vs upgrading it vs defending by depth is your call'). It stops short of saying when to prefer this over repair_building, demolish_building, or place_building.

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