pws_add_storyline_worker

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

Beyond the destructiveHint annotation, the description adds that the tool verifies persisted membership and defaults to preview, meaning no mutation occurs unless explicitly confirmed. This is valuable behavioral context, though it doesn't detail post-add effects. No contradiction with annotations.

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?

Three terse sentences with all information front-loaded; no wasted words. Every sentence adds a distinct piece of information.

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 destructive mutation tool with a confirmation flow, the description omits the role of 'confirmed' and doesn't explain what happens after a successful add. With no output schema and 0% schema coverage, this leaves significant gaps for the agent.

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%, so the description must compensate. It implies contractId and storylineId from the phrasing, and mentions 'Defaults to preview' for the preview parameter, but the confirmed parameter is entirely unexplained. No per-parameter details are given for the optional boolean.

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 clearly states the tool adds an active player-company contract to an active storyline, with preview as the default mode. This specific verb+resource combination distinguishes it from sibling tools like remove_storyline_worker and add_stable_worker.

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 usage for adding contracts to storylines and notes the preview default, but it doesn't explicitly state when to use this over alternatives or when not to use it. No exclusions or alternatives are mentioned, though 'Verifies persisted membership' hints at a precondition.

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