steal_tech_options

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

With no annotations, the description carries the full burden and does disclose a genuinely non-obvious behavior: the options are still listed on turn_status.todo.steal_tech even when blocking_name shows POLICY/PRODUCTION/etc., because the engine reports one blocker at a time. It does not state that the call is side-effect-free, but for a clearly query-shaped options endpoint the added engine-quirk context is substantial.

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?

Purpose is front-loaded in the first clause and every sentence carries information, but the second sentence is dense and parenthetical, mixing the player_id instruction with an unrelated engine caveat, which slightly hurts scannability.

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 zero-parameter tool with no output schema, the description adequately covers what comes back (civs plus techs per victim, with player_id) and where else the same data appears. Only the absence of any note on read-only/no-side-effect status keeps it from being complete.

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?

Zero parameters, so the baseline is 4. The description still adds meaning by explaining that each victim result carries a player_id intended to be forwarded to steal_tech, which is useful output-field semantics beyond the empty 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?

The description states a specific verb+resource: it returns the civs a finished spy can steal a tech from and the techs available from each. It is distinguishable from the sibling steal_tech, which it explicitly names as the follow-up action rather than a duplicate.

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?

It gives a clear trigger ('when a spy finished stealing') and routes the agent to the next tool, steal_tech, via the player_id field. It also notes the options appear on turn_status.todo.steal_tech, which is a concrete when-to-use pointer, though it never states when this call is NOT valid.

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