repair_building

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

With no annotations provided, the description carries the full disclosure burden and does well: it states cost (50% of build price, auto-charged), duration (2h), that the building keeps working at its current tier during the repair, and the one-tier restriction. This is concrete, non-obvious behavioral information that an agent needs before calling.

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 description fronts the key action, then packs cost and timing into the second sentence, then a helpful lookup hint. It stays mostly tight, but the closing metaphor about a damaged market being partially 'in existence' on the ground is a bit colorful and could be trimmed without losing essential meaning.

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 fairly simple 3-parameter tool with no output schema, the description provides the essentials: target eligibility, cost, duration, concurrent behavior, and a pointer to the damaged-buildings list. Minor gaps exist—no mention of an error/no-op case where no repair is needed, and no explicit note on what the API returns.

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%: api_key, territory_id, and building_type each have documented descriptions in the schema. The tool description adds no additional parameter-level details beyond what the schema already gives (e.g., it does not further clarify what building_type values mean), so the baseline score of 3 is appropriate.

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?

The description opens with a specific verb+resource combination: 'Repair a building damaged by raids/assaults back up one tier.' It states the exact trigger (damage from raids/assaults), the action (repair), and the scope (one tier), which differentiates it from siblings like place_building, build_structure, and demolish_building even without naming them.

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 description gives a clear usage gate: repair is appropriate when a building has been knocked below its built tier, and it tells the agent where to check eligibility (checkin.kingdom.damaged_buildings). It does not explicitly name alternatives or state when-not-to-use conditions, but the context for eligibility is strong.

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