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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds real value on top: 'Only non-null fields are updated' clarifies partial-update semantics, and the explicit warning that seliee_collection_faqs replaces the whole FAQ list discloses destructive overwrite behavior the annotations cannot express. It omits auth requirements, validation failures, and what happens if neither identifier is supplied.

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?

Three sentences, front-loaded with the action and lookup keys, then the null-handling rule, then the one non-obvious destructive edge case. No filler and no repetition of schema content.

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 destructive 11-parameter mutation with no output schema and no annotations beyond hints, the description covers the essentials: what gets changed, how it's targeted, what is preserved, and what is wholesale replaced. Remaining gaps are error behavior when both identifiers are null and lack of field-level detail, which are moderate rather than blocking.

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% across 11 parameters, so the description must compensate. It explains the id/uuid lookup pair and the {'summary','text'} shape plus replace-all semantics of seliee_collection_faqs, but leaves the nine scalar seliee_collection_* fields entirely to their self-descriptive titles, with no formats, constraints, or enum-like value guidance.

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 clear verb+resource (edit fields of an existing seliee_collection) and specifies the lookup keys. It does not explicitly distinguish itself from update_collection_keys, publish_collection, or create_collection, so it stops short of a 5.

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?

Says the collection must already exist and be located by id or uuid, which implies 'use this for updates, not creation.' However, it never names alternatives (update_collection_keys, create_collection, publish_collection) or states exclusions, so the routing guidance is only implied.

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