Update Entities

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

Annotations already declare the safety profile (destructiveHint=true, idempotentHint=false). The description adds real behavioral context beyond them: the operation preserves existing observations and relations, which is exactly what an agent needs to know to prefer it over delete+recreate. It does not disclose what happens on a name collision or a missing entity, hence not a 5.

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?

One sentence of about 30 words with the decision rule front-loaded and the capability statement second. Nothing is redundant, though the sentence is slightly overloaded with a colon-joined clause.

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?

Output schema exists, so return values need no explanation, and annotations cover the safety profile. However, for a destructive, non-idempotent mutation with a nested array payload and siblings like merge_entities and read_conflicts, the description is silent on collision handling, not-found entities, and partial-batch failure.

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?

Top-level schema coverage is 0% for the single `entities` parameter, so the description must carry meaning. It does: rename and/or entity-type change are partial updates, and the preservation clause clarifies that unspecified fields are untouched. It does not describe the array/batch shape or per-item failure behavior.

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 set (rename, change entity type) on a specific resource (existing entities) and explicitly frames itself as the non-destructive alternative to delete-then-recreate. An agent can distinguish it from delete_entities, create_entities, and update_observations without opening any 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?

"Prefer this to deleting an entity and re-creating it under another name" is an explicit when-to-use rule with a named alternative pattern. It stops short of saying when NOT to use it, e.g. that merge_entities is the right sibling for consolidating duplicates or that read_conflicts should be consulted first.

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