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

Goes well beyond the annotations (readOnly=false, destructive=false, openWorld=true) by disclosing the per-call cap (20, or 10 for Canva/Descript), that render-first sources can take up to 2.5 minutes, and that failures are partial ('Items that fail don't stop the others'). It also describes the per-item return shape (video_upload_id, caption, title, or ok:false with an error), which is exactly the behavior an agent needs before a slow mutation.

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, then caps, then options, then returns — a sensible order with no filler sentences. The nested parenthetical '(the per-call cap is max_per_import from the source list, usually 20; Canva and Descript cap at 10)' is information-dense but awkwardly embedded mid-sentence.

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 6-parameter, nested-object, open-world mutation with no output schema, the definition covers caps, latency, partial-failure semantics, and return fields, which is close to sufficient. It omits any permission or connection prerequisite (e.g. whether the source account must be linked to the workspace) and whether the call blocks for the full 2.5 minutes.

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?

With 83% schema coverage the schema already documents most fields, but the description adds real meaning the schema lacks: container_id's purpose for project-based sources and concrete `options` payloads per source ({ format: "landscape" } for twitch, { version: "captioned" } for heygen, { format: "mp4" } for canva) for an otherwise free-form additionalProperties object. It says nothing extra about workspace_id or idempotency_key, so 4 rather than 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 ('Imports items ... into a workspace library') and ties the input to a named producer ('items found with list_import_items'), which immediately separates it from upload tools like create_video_upload. An agent knows what entity it moves and where it lands 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 routing context: call list_import_items first, pass container_id for sources with projects, and send create_post_drafts/create_carousel the returned video_upload_id, so downstream usage is clear. It never states a when-not condition and does not disambiguate against the overlapping sibling import_opusclip_clips, which keeps it from a 5.

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