create-collection

name	create-collection
type	primitive
description	Create a Collection object and bind to variable

Create-Collection

INPUT CONTRACT

• value (required): One of:
  • Array of $variables (e.g. ["$note1", "$note2"])
  • Array of raw resource IDs (e.g. ["Note_42", "Note_43"])
  • A single $variable (e.g. "$note")
  • Empty array [] (creates an empty Collection)
• out (required): $variable name for resulting Collection
• name (optional): Stable name for the Collection, enabling later load by name

REQUIREMENTS:

• value must be provided (can be empty array)
• out must be a $variable
• All elements of value (whether $variables or raw IDs) must resolve to existing Notes

IMPORTANT: The name parameter registers a persistent name for later retrieval via load(target="my-name"). Variable names like $my_collection in out are temporary bindings during plan execution — not persistent names.

Code-block usage tip: When filtering an existing Collection in a code block, you typically end up with a list of raw Note IDs from get_items("$source_collection"). Pass that list directly as value — there is no need to round-trip each ID through a $variable. Example:

items = get_items("$titles_collection")
filtered = [tid for tid in items if not get_text(tid).startswith("[")]
tool("create-collection", value=filtered, out="$filtered_titles")

EXAMPLES

{"type": "create-collection", "value": ["$note1", "$note2"], "out": "$my_collection"}

{"type": "create-collection", "value": ["Note_42", "Note_43"], "out": "$by_id"}

{"type": "create-collection", "name": "research", "value": [], "out": "$papers"}

{"type": "create-collection", "value": "$note", "out": "$single_item"}

OUTPUT

Returns success with the created Collection's resource ID. The Collection is immediately available via the $variable bound in out.

FAILURE SEMANTICS

• Missing value or out parameter
• Referenced $variables in the array do not exist

ANTI-PATTERNS

• Confusing name (persistent identifier) with out (temporary binding)
• Using create-collection to inspect or read existing Collections — use load instead