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

Despite having annotations (readOnlyHint=false, destructiveHint=true), the description adds critical behavioral context: pausing stops everything, status changes launch/unlaunch, the seat rule enforcement with fallback to draft, kicking due lanes on launch/resume, and the impact on monthly lead quota and acting from the human's account. This goes beyond what annotations alone convey.

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 well-structured and front-loaded with the core purpose, then details switches and account-level settings, then the seat rule, then usage caution. Every sentence adds meaningful information without redundancy. It is concise given the complexity of the tool.

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?

Given the tool's complexity (8 parameters, nested object, account-level effects, and conditional behaviors), the description covers all necessary aspects: parameters, side effects, preconditions (seat rule), and when to use it. It even notes what it does not affect (autonomy ladder). No essential information is missing for an agent to call it correctly.

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 description significantly enriches parameter understanding beyond the schema: it clarifies that dailyCap and workingHours are account-level (shared across plays), gives the default dailyCap (145), provides a workingHours format example, and explains the semantic difference between paused and status. This is valuable for correct invocation, especially since schema coverage is already high.

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's purpose: updating a play's own knobs (name, goal, voice), its two switches (paused, status), and account-level pacing settings. It distinguishes from siblings by explicitly saying it does not touch the autonomy ladder and by focusing on modification rather than creation or listing.

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 provides explicit usage guidance: launch/resume only when the human asked in this conversation, and explains the seat rule that prevents launch/resume without a live LinkedIn seat. It also differentiates between per-play and account-level settings, and notes that it does not affect the autonomy ladder, helping the agent choose correctly among siblings.

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