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

Annotations only declare the safety profile (non-destructive, non-idempotent, closed-world); the description adds substantive behavior the annotations cannot convey: narration is auto-generated and saved in the supplied language, a slide UID at a narrated internal boundary may be refused, and scriptGenerated=false signals a partial-success state that must not be re-inserted. It also encodes a user-consent requirement, which is important for a mutating 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 purpose and the recording-selection guard, then placement, then the retry path — a sensible order. It is on the long side, and the sentence about slide UIDs at narrated boundaries repeats the anchor parameter description nearly verbatim, so there is some redundancy against the schema.

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 an output schema present, return values need no explanation; the description instead covers everything else an agent needs: workspace membership constraint, language generation, anchor selection strategy, consent gating, and the recovery path when script generation did not occur. Nothing material is missing for a 5-parameter mutating tool.

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 100%, so baseline is 3, but the description adds real meaning: the language defaulting rule (project language from get_project, else en-US), title defaulting to the recording title, and which anchor kinds are reliable versus refusal-prone. The anchor guidance is partly duplicated in the schema's own anchor description, which keeps this just short of a 5.

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 ("Insert a ready screen recording ... into an existing project") and identifies the upstream source tool (list_screen_recordings), which cleanly separates it from create_project_from_recording and the slide-level siblings. An agent can distinguish it without opening the schema.

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 explicit preconditions ("Call only when the user explicitly asks for this change", recording must belong to the project workspace), an anti-pattern with reasoning (never choose by result order/recency/single-result), and a named alternative for the already-inserted case (retry_video_segment_script_generation with returned ids). This is when/when-not/alternative guidance in full.

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