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

Annotations already establish readOnly/non-destructive, so the description's marginal value is in cost behavior ('Free, generates nothing') and in disclosing that the payload carries stale flags, approval states (active, pending_funding, pending) and the held authority. Those are genuine behavioral facts an agent would not get from the schema; it stops short of saying what the approval states mean operationally or what happens when scripts are stale.

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 whole definition is a single run-on sentence that mixes return-field documentation, customer-facing scripted language ('say: show say'), and next-tool arguments without any separating structure. Field descriptions are crammed inline with parentheticals, making it hard to scan for the key fact (what to pass to approve_season_scripts).

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?

With no output schema, the description rightly spends most of its words documenting the return payload (credits, hash, approval, create_series args), which is necessary and useful. It leaves gaps on the single input parameter, on what to do when no scripts exist or when the stale flag is set, and the embedded conversational instructions blur the line between tool behavior and agent prompting.

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 had to carry the meaning of series_id, and it never mentions the parameter at all. An agent must infer that the ID comes from list_series or get_series with no guidance on format or source.

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 makes clear this is a retrieval tool ('generates nothing', 'Every season script with its craft_check, price and stale flag') and enumerates the returned payload, which distinguishes it from generator siblings like make_episode or generate_video. It is less crisp than a verb-first sentence because it leads with 'Free, generates nothing' and then lists fields rather than stating 'Returns all season scripts and the season price'.

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?

It gives a concrete downstream workflow: present 'say' to the customer, ask once, and on yes call approve_season_scripts with scripts_hash and max_credits set to total_credits. That is explicit next-step routing, but there is no comparison against alternatives such as get_season_costs, quote, or get_episode_script, and no stated condition for when this tool is *not* the right call.

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