city_state_actions

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

With no annotations, the description carries the full behavioral burden. It adds useful detail (kill-camp x/y only when the camp is revealed, tribute paying gold or a Worker, that `details` explains the strength check), which is real beyond-schema context. But it never states whether the tool is read-only or mutating, nor any permission or side-effect behavior, leaving a key gap for a tool whose name implies mutation.

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 single dense sentence is not front-loaded with a clear statement of purpose and instead leads with a cross-reference ('beyond gifts') before burying the actual content list. Internal field names (quest_list, details) and sibling references add clutter without improving the opening.

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?

With no output schema and no annotations, the description does partially describe return content (influence, structured quest fields, contest scores, tribute strength check), which is valuable. But it omits the sole parameter and leaves the read-vs-write nature unresolved, so it is only partially adequate for a no-schema, no-annotation tool.

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 description coverage is 0% and the single required parameter player_id is never mentioned, explained, or given format/scope meaning in the description. The description must compensate for the coverage gap but does not, so an agent learns nothing about the argument from either source.

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 names the resource (the city-state screen) and enumerates the content it exposes (influence, quest list, protection, tribute, war/peace), but never uses a clear verb and blurs whether it reports availability ('Whether I can pledge') or performs these actions, despite the name suggesting 'actions'. It does distinguish itself from the sibling city_state_gifts by scoping to content 'beyond gifts'.

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 phrase 'beyond gifts' implicitly routes the agent away from city_state_gifts and toward this tool for the rest of the city-state screen, and a sibling quests/quest_list relationship is implied. However, there is no explicit when-to-use statement, no conditions that select this over city_state_action or diplomacy, and no exclusions.

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