telys_create_collection

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

Discloses key behavior beyond annotations: the collection is built but NOT persisted until a mutating tool writes to it, telys_list_collections won't show it until then, and repeated calls with the same name return the existing collection unchanged. These details align with and enrich the idempotentHint annotation.

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 description is dense but every sentence earns its place: purpose, alternative usage, parameter semantics, persistence caveat, and idempotent repeat behavior are all covered. It front-loads the core action and follows with the most important caveats, with no filler.

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?

Given the minimal schema and absence of an output schema, the description is remarkably complete: it covers what the tool creates, how to use it, parameter details, persistence behavior, listing visibility, and idempotence. An agent has enough to invoke it correctly and predict its side effects.

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%, so the description fully carries parameter explanation. It states name is required, defines partition_by as a single metadata key name, gives its default 'scope', and warns that compound keys must be composed into one string — meaningful guidance beyond the bare schema.

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 action — create a named Telys memory collection in the active store — and distinguishes it from telys_add, which auto-creates on first write. It also clarifies that the collection is wired to the built-in embedder, making the tool's role unmistakable among the sibling tools.

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?

Explicitly says the tool is optional because telys_add auto-creates, and tells the agent when to prefer this tool: when you need to fix the name and partition key up front. This gives clear decision guidance versus siblings and covers the non-persistence consequence.

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