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

The description adds value beyond the annotations by stating the return payload ("This returns its id") and by spelling out the idempotency contract in operational terms ("Reuse request_key only for the same exact request"), which sharpens the idempotentHint flag. However, annotations declare destructiveHint=true for what is nominally a create operation, and the description neither explains nor reconciles that risk profile, nor does it mention permissions or what happens to an existing document at the same location.

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?

Four short sentences, front-loaded with the action and followed by return behavior, scope caveat, and parameter rules. Every sentence carries information; only the slightly vague phrasing "in this document home and season scope" costs a point.

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?

An output schema exists, so return values need not be described in depth, and the annotations cover safety flags. What remains missing for a 6-parameter mutation tool is the meaning of folder_id and season_id and any note on required permissions or placement conflicts, leaving the definition adequate but not complete.

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 only 33% — title and body are documented in the schema while folder_id, season_id, workspace_id and request_key are not. The description compensates for workspace_id (source directory) and request_key (idempotency semantics), and gestures at season_id via "season scope," but folder_id is entirely unexplained by either schema or description.

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 leads with a specific verb+resource ("Create a document") and constrains it to the document home and season scope, and it explicitly notes that it "does not change the workshop subject," which separates it from the save_workshop_document / save_series_document family. It never names the closest sibling (native.create_document or create_studio_document_folder), so the agent must infer which document-creation entry point applies.

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?

There is real guidance on the workspace_id argument ("use workspace_id from the authorized Film, Series or GenAds directory") and on request_key reuse, but no explicit statement of when to prefer this tool over native.create_document, save_workshop_document, or save_series_document despite those siblings being present. The exclusion ("does not change the workshop subject") hints at an alternative without naming it.

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