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

Annotations only declare the safety profile (non-read-only, idempotent, non-destructive), while the description adds the crucial behavioral detail: this is a merge/patch operation where omission preserves state and null clears it. It also discloses concrete guardrails (clip up to 60 seconds and adds to video length, dim 0.2-0.85, volumes 0-1) that go well beyond structured fields. It stops short of describing failure behavior or atomicity when a slot contains an invalid asset id.

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 purpose is front-loaded in one short sentence, which is good, but the remainder collapses three levels of nesting into a single dense block of comma-chained clauses that is hard to scan under time pressure. Almost every clause carries information, but a nested list or a per-slot structure would convey the same content far more parseably.

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 a four-parameter tool whose schema is entirely untyped objects, the description covers all four top-level parameters with their nested shape, states the patch semantics, and names the asset-source constraint — enough for an agent to attempt a correct call. Gaps remain around error handling, whether partial failures roll back, and what happens when quiz-level background and question-level background conflict.

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% and all four parameters are opaque objects/arrays with additionalProperties true, so the description carries the full documentation burden — and it does so in detail, spelling out nested fields for quiz background, intro/outro, soundEffects with per-name volume keys, question clips, and answer images. It is not exhaustive (e.g., valid ranges of trimStartSeconds/trimEndSeconds, what fields a question object accepts beyond id/image/clip/background, whether nested omission semantics also apply inside arrays).

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 opening sentence 'Attach uploaded files to a quiz' gives a concrete verb and resource, and the rest enumerates exactly which slots (quiz, questions[], answers[]) get media. It is clear what the tool does, but it never explicitly contrasts itself with siblings like quiz_video_get_quiz_media or quiz_video_create_media_upload — the agent must infer that 'uploaded' means assets already in the library.

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?

'Omit a slot to leave it, send null to clear it' is genuine usage guidance that defines the patch contract, and 'Only asset ids from your own library are accepted' states a hard prerequisite. What's missing is an explicit pointer to the upstream tool (create/complete media upload) needed to obtain those asset ids, and no statement of when to use this versus quiz_video_update_quiz.

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