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

Annotations declare destructive/idempotent/openWorld, but the description goes well beyond them: it discloses the required `screen.cast` permission, the lasting-vs-timed semantics, that screens are notified at once, and the partial-failure contract (skipped screens counted as notShared/needsApproval instead of failing the call). That partial-success behavior is the kind of thing an agent genuinely needs and cannot get from structured fields.

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?

One dense paragraph, front-loaded with the core distinction before targeting modes and failure semantics. Every clause carries information, though the mid-paragraph switch between targeting, notification, and error handling makes it slightly harder to scan than a short bulleted split would be.

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?

An output schema exists so return values need not be spelled out, and the description still notes that the response names changed screens. With permissions, failure modes, targeting, and the clearing path all covered, nothing needed to call this correctly is 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 coverage is 100%, so baseline is 3, but the description adds real meaning: nodeId is illustrated with a concrete use case ('all California stores' in one call), the combination rule between screenIds and nodeId is restated at the tool level, and the null-clears-one-screen constraint is called out with its single-screen limitation. It does not, however, explain contentId/contentKind pairing beyond what the schema says.

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?

States a specific verb and resource ('Change what screens play by default') and immediately scopes it as a lasting assignment rather than a timed takeover, which is exactly the axis that separates it from cast_content. An agent can distinguish it from all siblings without opening a schema.

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?

Explicitly routes: 'Use cast_content for a temporary takeover that ends by itself, quick_post to write and show a new message.' It also states when it applies (default, lasting, until changed) and enumerates the three targeting modes plus their combination rule.

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