atom-ops

Single-atom edits via mcp__catgo__catgo_structure. The default exploration path lists structure-tool actions, reads several skill docs, and queries the current viewer state before each action — that is 4–8 MCP calls for a one-atom edit and the user sees "Thinking…" for 15–30 s. This skill collapses every common operation to a single call.

When to use this skill

• Adding one atom (or a small handful) at known coordinates or a known relationship to an existing atom.
• Deleting atoms by index or by element.
• Replacing an atom's element without moving it.
• Moving an atom by index to a new position.

If the user wants to add a molecule or cluster (CO, H₂O, NH₂, …) onto a surface, stop and use the structure/cluster_ops skill instead — placing a molecule needs adsorbate placement and site selection, not raw atom addition.

Operation cheat sheet

Every recipe below is a single mcp__catgo__catgo_structure call. Each item lists the action, the required params, and the typical user phrasing.

Add a single atom at explicit Cartesian coordinates

User: "Add an H at (1.5, 2.0, 6.3) Å"

{"action":"add_atom","element":"H","position":[1.5,2.0,6.3]}

Add an atom near another atom (height above a site)

User: "Place a hydrogen 1.0 Å above atom 12"

You need the position of atom 12. Two paths:

1. If the user just told you the coordinate, use it directly with position.
2. Otherwise call mcp__catgo__catgo_structure {"action":"get_info"} once, find the site, add [0, 0, height] to its xyz, then issue add_atom. Do not call get_info more than once per chat turn — re-use the result.

For atoms placed on a slab surface (above the topmost layer), use mcp__catgo__catgo_structure {"action":"add_atom","element":"H","position":[x,y,z]} where z = (highest-atom z) + bond length (typical: O–H 1.0 Å, H–metal 1.5 Å, C–metal 2.0 Å).

Delete atoms by index

User: "Delete atoms 5, 6, 7" or "remove the last 3 atoms" or "删除 5 到 9"

{"action":"delete_atoms","indices":[5,6,7]}

Indices are 0-based and refer to the current viewer site order. For ranges, expand them yourself (5,6,7 not 5-7). For "the last 3 atoms" you need get_info to know the site count first; same single-call-per-turn rule applies.

Delete all atoms of an element

User: "Remove all hydrogens"

{"action":"delete_atoms","element":"H"}

This is faster than enumerating indices when the user names an element.

Replace an atom's element

User: "Swap the oxygen at site 3 for fluorine" or "把 site 7 的 C 换成 N"

{"action":"replace_atom","index":3,"new_element":"F"}

This is substitution at a fixed position — the element changes, the xyz stays. For systematic element-screening across many sites, use the dedicated structure/substitution skill instead.

Move an atom to a new position

User: "Move atom 12 to (2.0, 3.0, 5.5)"

{"action":"move_atom","index":12,"position":[2.0,3.0,5.5]}

For relative moves ("shift atom 12 by 0.5 Å along z"), compute the new absolute position yourself from get_info once, then call move_atom.

What NOT to do

These patterns are slow and add no value:

• Listing all structure-tool actions ({"action":"list"} or similar discovery calls) before doing the edit. The actions above are the complete set you need.
• Calling get_info repeatedly to verify each edit succeeded. CatGo's viewer reactivity already shows the change; the tool response confirms it; re-fetching wastes round-trips.
• Asking the user to confirm "which atom" when the indices are obvious from their message. Confirm only when the request is genuinely ambiguous ("remove the carbon atoms" with multiple carbons in different chemical environments — confirm which set).

After-edit confirmation

One sentence stating what changed. Mention the new total atom count if it changed.

Added one H at (1.5, 2.0, 6.3). Structure now has 13 atoms. Deleted atoms 5–9. Structure now has 27 atoms. Replaced O at site 3 with F. Composition: Ti2O3F.

Do not dump the full site list or coordinates back to the user — the viewer shows the result.