pws_set_championship_active

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

The annotations already declare destructiveHint=true, so the description doesn't need to re-state destructiveness. It adds value by clarifying that the operation does NOT delete history, which is a significant behavioral guarantee. It also mentions the preview capability, providing transparency about a non-destructive first step. This goes beyond the structured annotations without contradicting them.

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 single, compact sentence that front-loads the core action and its key outcome. Every word earns its place: 'PREVIEW OR' signals the two modes, 'RETIRE/REINSTATE' states the verb, and 'without deleting its history' provides a critical constraint. There is zero waste, and the structure immediately informs the agent of the tool's nature.

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 mutation tool with 4 parameters, no output schema, and no parameter documentation, the description is incomplete. It does not explain the safe execution flow (preview then confirm), the meaning of the boolean flags, or the exact effect of 'active'. An agent cannot determine how to correctly invoke the tool (e.g., whether preview must be called with confirmed, or if active is true for retire or reinstate) from this description alone. Substantial details are missing.

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%, meaning no parameter descriptions exist in the schema. The description does not explain the meaning of 'active' (whether true means retire or reinstate), the role of 'preview' (beyond the vague word), or the purpose of 'confirmed'. It relies entirely on parameter names for semantics, which is insufficient for a 4-parameter mutation tool. The description fails to compensate for the schema gap.

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 action (retire/reinstate) on a specific resource (player-company championship) and adds a key qualifier ('without deleting its history'). It also mentions a preview mode, clearly distinguishing it from read-only tools like pws_get_championships and from other mutation tools like pws_award_championship or pws_vacate_title. The purpose is unambiguous and differentiated.

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 implies when to use the tool (to change the active status of a championship) but provides no explicit guidance about when NOT to use it or how it compares to similar siblings like pws_vacate_title. The mention of 'PREVIEW OR' hints at a workflow but doesn't explain when preview is appropriate versus direct execution. Usage context is implied rather than explicitly stated.

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