Venue Set

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

With no annotations, the description carries the full burden and does contribute real behavioral facts: no secret is ever stored here, output defaults to yes where the site takes video, and the call returns what the venue still needs plus an exact terminal command. It never says whether reusing an existing name overwrites or errors, who is allowed to set a venue, or whether changes are reversible — meaningful gaps for an unannotated mutation tool.

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?

Front-loaded with the purpose and the 'no secret' warning before the parameter walkthrough, and every clause carries operational detail rather than filler. The single dense paragraph is hard to scan and the script/loop sentence is compressed to the point of ambiguity, which keeps it off a 5.

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 an 11-parameter unannotated upsert with an output schema present, this covers nearly everything an agent needs to construct a valid call, and the return-value mention is useful even though the output schema also documents it. The missing overwrite/idempotency semantics and the undocumented 'note' field are the remaining holes.

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 do all the work and largely does: it decodes platform's allowed values (fake, twitch, youtube, kick, owncast, rtmp output-only, file), reinterprets 'channel' per platform (login name, handle/id, server address), and gives poll_s's default of 10 with a floor of 5 plus the script element shape. Only 'note' is left undefined and 'loop' is only loosely tied to the scripted-viewer sentence.

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+resource ('Add or change a venue') and immediately pins the granularity: 'one channel on one site.' That scope sentence alone separates it from venue_list/venue_remove and from stream_* tools that actually push the stream.

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 per-platform applicability rules that function as usage conditions: script/loop are 'fake only', reader/poll_s are 'youtube only', rtmp is 'output only', file means channel is an .flv path. It also points at stream_go as the consumer of the output flag. It never states exclusions such as 'use venue_list to inspect first' or 'do not use this to start streaming', so it lands short of a 5.

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