Stream Panel

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

With no annotations, the description carries the full burden and does so well: it discloses self-refresh roughly once a second with 'no blip', one-panel-per-kind constraint, patch semantics ('fields you leave out keep their value'), empty-panel hiding unless `empty` is supplied, and `on=False` removal. It even surfaces the moderation risk that viewer-authored text is rendered verbatim.

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?

It is front-loaded with purpose then usage, which is good, but the body is a dense unbroken paragraph mixing kind semantics, parameter details, and safety advice. For 11 parameters some length is justified, yet bullet-style segmentation and removal of redundant restatement would improve scanability.

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 no explanation, and the description covers the mutation model, defaults, and per-kind behavior thoroughly. Missing pieces are minor but real: coordinate units for x/y/w, the accepted values for `anchor`, and the permitted keys of the nested `style` object.

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 0% across 11 parameters, so the description must compensate, and it largely does: it defines the kind values, rows range (1-12), title (including '' for none), empty behavior, on=False, venues filtering, and the patch semantics of omitted fields. Gaps remain for x/y/w units and the full `style` object shape, which is deferred to stream_callout with only `accent` described.

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 — 'Show the stream's own data on screen in a panel on the visual page' — and enumerates the four panel kinds (now, requests, chat, credits) with what each displays. It also implicitly separates itself from stream_callout by deferring to it only for positioning/style conventions.

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?

Gives an explicit trigger: 'Reach for it when viewers should see where the set is', with three concrete scenarios (request line, whose request plays now, recent chat). It adds a useful no-kind fallback (lists panels and their current contents) and an operational warning (take the chat panel down if chat turns bad), but never names a sibling alternative or an explicit when-not condition.

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