edit_show

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

With no annotations, the description carries the full burden and does well: it discloses partial-update semantics, the important exception that tags/sections/hosts are replaced wholesale, that hosts=[] clears hosts, and that only one visibility value should be sent per request. It omits auth requirements and the effect on fields like publish_date, keeping it short of a 5.

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 core action and key format, then the partial-update rule and its exception, then visibility. Every clause carries information an agent needs; there is no filler.

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 mutation tool with no annotations and no output schema, the description covers the behavioral traps well but says nothing about permissions, what a successful response looks like, or the remaining plain parameters. It is close to complete for invocation but not fully so.

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 supply meaning, and it does for the non-obvious parameters: key format, wholesale replacement of tags/sections/hosts, hosts=[] removal, and the visibility enum values. Self-evident booleans and strings (hide_stats, disable_comments, name) are left to their names, which is reasonable but leaves some params undocumented.

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 ('Edit') and resource ('one of your shows') with a scope qualifier and a concrete key example, which distinguishes it from get_show, upload_show, and user_shows in the sibling list.

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?

Explains the key format, that omitted fields are left unchanged, and the three visibility modes with their meaning. It does not, however, name when to prefer this over alternatives like upload_show or get_show, so the routing guidance is implicit rather than explicit.

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