add_mass_trait_to_entity

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

Annotations only cover the safety profile (readOnly false, idempotent false); the description goes well beyond them by disclosing the archetype-migration mechanism and the critical side effect that EVERY entity sharing the archetype receives the tag. It also names the exact return fields, which is valuable given there is no output schema. It stops short of addressing idempotency or error behavior beyond the schema's note on invalid handles.

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 critical caveat about archetype-wide effect is front-loaded right after the purpose, which is the correct priority. It is slightly redundant, restating the old/new_archetype_id and changed return values in both the prose and the explicit Returns line.

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 mutation tool with no output schema, the description supplies the return shape, the inverse operation, the scope restriction (editor, not PIE), and the archetype side effect. The one remaining gap is the failure/error semantics for invalid tags, though the schema partially covers the invalid-handle case.

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 100%, so the baseline is 3; both parameters are fully documented in the schema. The description reinforces the tag semantics (a tag, not a trait/fragment) but adds no format or resolution detail beyond what the schema already provides for tag and entity_handle.

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 (add) and resource (FMassTag to a Mass entity), and explicitly resolves the naming trap by saying it is a tag, not a trait or fragment, despite the name. It scopes the operation to the editor world rather than PIE. It does not, however, differentiate itself from the similarly named sibling add_mass_trait, leaving a real ambiguity unresolved.

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?

Gives useful context (editor world, not PIE) and points to the inverse tool remove_mass_trait_from_entity, and the archetype caveat implicitly warns when this is the wrong choice for a single-entity edit. But it never states when to prefer this over the sibling add_mass_trait, so the agent must infer the distinction.

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