claim_territory

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

With no annotations, the description carries the full behavioral burden, and it delivers richly: it discloses automatic x402 payment with live discounts, that free claims skip the price curve and never refill, the base/fair-share vs growing-multiplier price shape, the shield cap, the capital/border/colour constraints, and even the resolution path via change_color for heraldry clashes. It clearly exceeds the schema data and gives an agent a realistic model of what will happen.

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 is a dense block of text with ALL-CAPS key terms and semicolon-packed clauses, but every sentence earns its place: free claims, the price shape, the time period shield cap, placement logic, and the pointer to the full rules endpoint. It is front-loaded with the core action and keeps the most important facts near the beginning, though the long layout is less scannable than it could be.

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 tool with no output schema, the description covers the main external constraints an agent must respect: cost, free claims, shield cap, border requirement, and heraldry clash. It points to GET /api/v1/actions/rules for full constraints and to the check-in for pricing details. The main gaps are that it does not describe the response shape of a successful claim and does not explicitly name how to find eligible neutral territories via a tool like get_neutral_territories, so the agent must rely on the rules endpoint.

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?

The schema already covers 100% of the parameters, defining api_key and territory_id as 'UUID of the territory to claim'. The description adds selection context the schema cannot: the territory must be neutral, must border your land for later claims, must not carry a colour matching a neighbouring kingdom, and may be capped by the shield state. It also tells the agent where to look up free_claims_remaining and the next price, which directly informs which territory_id is worth passing.

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 the specific verb+resource pair 'Claim a neutral territory' and goes on to pin down the exact scope: the first claim founds a capital anywhere, while every later claim must border your land and is blocked by a heraldry clash. This makes the purpose unambiguous and clearly distinct from related actions such as get_neutral_territories, relocate_capital, or claim_income.

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 strong conditional usage guidance: use it for your free pre-paid first claims, use it after that only when your wallet can pay the quoted price, and use it only when the territory is neutral, bordering, and not subject to a heraldry clash. It does not explicitly name sibling tools to compare against, but it directs the agent to the full constraints endpoint and the check-in line for prices, share, and count.

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