Set the working directory for all subsequent file I/O.

WHEN TO USE

Call this first when the user's PDB files are in a specific directory and you want to avoid writing absolute paths in every subsequent call. After this call, relative paths in all other tools resolve against path.

Inspect a PDB file and return a detailed chain-level summary.

WHEN TO USE

Always call this FIRST before any fixing or relaxation. The output tells you what is actually in the file so you can make informed decisions about every subsequent step.

WORKFLOW POSITION

Step 1 of every session. Re-run after split_pdb if you need per-component details.

OUTPUT — WHAT TO CHECK

chains[*].type Confirm which chains are protein, DNA/RNA, ligand, or water. Ligand chains (type="ligand") cannot be directly relaxed with the built-in presets; they must be removed with fix_pdb_structure unless they have standard force-field parameters.

chains[*].numbering_gaps Each gap lists the flanking residues and the estimated number of missing residues. Gaps ≤ 5 residues are commonly modellable with fix_missing_residues=True. Larger gaps produce poor geometry and should be left open unless the user specifically requests loop modelling.

chains[*].structural_breaks A structural break that COINCIDES with a numbering gap is strong evidence for genuinely missing coordinates. A structural break WITHOUT a numbering gap may indicate a clashing insertion or bad crystal contact — flag this to the user.

chains[*].sequence Verify the sequence is complete and plausible. Unknown residues appear as [XXX].

Split a multi-component PDB into separate files by molecular type.

WHEN TO USE

Use when query_pdb_structure reveals a mix of protein, nucleic acid, and/or ligand chains that need to be processed differently. Common reasons:

• You want to fix the protein chain but retain the ligand as-is.

• The structure contains DNA/RNA that requires different force-field treatment from the protein.

• You want to inspect or modify a single chain in isolation.

WORKFLOW POSITION

Optional step between query_pdb_structure (step 1) and fix_pdb_structure. After splitting, run fix_pdb_structure on the protein file, then use assemble_pdb_structures to recombine before relaxation.

OUTPUT — WHAT TO CHECK

Verify that the ligand list matches what you saw in query_pdb_structure. If a ligand is missing, it may have been classified as an ion (and silently dropped) or the HETATM record name was not in the ligand detection list.

DECISION GUIDANCE

output_prefix: Use a descriptive prefix so file names are clear, e.g. "my_protein" yields "my_protein_protein_A.pdb".

Prepare a PDB file for OpenMM by correcting common structural problems.

WHEN TO USE

Run this after query_pdb_structure (and optionally split_pdb) and before relax_pdb_structure. It is required before relaxation because OpenMM needs: (a) standard residue names, (b) all heavy atoms present, (c) hydrogen atoms added.

WORKFLOW POSITION

Step 3 (or step 2 if no splitting is needed). Input is typically the raw PDB or the protein-only file produced by split_pdb.

DECISION GUIDANCE

chains_to_keep / chains_to_remove: Decide based on query_pdb_structure output. For a standard relaxation workflow keep only the biological unit (usually protein chains). Remove chains that are crystallographic symmetry mates or that lack force-field parameters.

ph (default 7.0): Controls protonation states of HIS, ASP, GLU, LYS, CYS. Use 7.4 for physiological simulation. Use the experimental pH if known from the paper. Histidine protonation is particularly sensitive — consider whether HID/HIE/HIP matters for your system.

remove_heterogens (default True): Set False only if ligands have been separately parameterised and the assembled structure is ready for a non-standard force field. For standard AMBER/CHARMM relaxation, ligands without parameters will cause createSystem() to fail.

keep_water (default False): Set True only when crystallographic waters are meaningful (e.g. active-site waters). Waters slow minimisation and are usually re-added during explicit-solvent solvation later.

fix_missing_residues (default False): Only enable for gaps ≤ ~5 residues or when the user explicitly requests loop modelling. Modelled loops have roughly-placed atoms and require extensive MD to be meaningful. Large gaps (> 10 residues) will produce severe clashes and should be left open.

fix_terminal_residues (default False): Disordered termini are almost never worth modelling; leave False unless specifically requested.

OUTPUT — WHAT TO CHECK

nonstandard_residues: List what was converted. Flag any unexpected conversions to the user (e.g. a bound cofactor being converted to a standard amino acid). missing_atoms_added: Review side-chains added. A large number (> 20) suggests significant disorder in the crystal structure. heterogens_removed: If this is 0 when ligands were present, something was misclassified — re-check with query_pdb_structure.

Merge multiple PDB files into a single PDB file.

WHEN TO USE

Use after split_pdb + fix_pdb_structure when you have separately processed components (e.g. fixed protein + original ligand) that need to be recombined before relaxation. Also useful for building hetero-complexes from individual chain files.

WORKFLOW POSITION

Optional step between fix_pdb_structure and relax_pdb_structure.

DECISION GUIDANCE

chain_id_map: Always provide this if you have performed split → fix → assemble, because fix_pdb_structure may have altered chain IDs. Map by the basename of the input file (e.g. {"protein_A_fixed.pdb": "A"}).

handle_conflicts (default "rename"): Use "rename" (default) for most cases — it is safe and non-destructive. Use "merge" only when two files represent the same biological chain split across files (e.g. modelled N-terminal extension + crystal structure). Never use "error" in automated workflows.

renumber_residues (default False): Only set True if downstream tools require sequential numbering from 1. Renumbering loses the original residue IDs, which makes cross-referencing with the source PDB harder.

renumber_atoms (default False): Set True if the output PDB will be read by tools that expect strictly sequential atom serials.

OUTPUT — WHAT TO CHECK

Run query_pdb_structure on the assembled output to verify chain IDs, residue counts, and that no unexpected gaps were introduced by the merge.

Energy-minimise and optionally run short restrained MD on a prepared PDB.

WHEN TO USE

Use as the FINAL step after fix_pdb_structure (and optionally assemble_pdb_structures). The input MUST have hydrogens and standard residue names — run fix_pdb_structure first.

Do NOT pass a raw PDB straight to this tool. OpenMM will fail if residues are missing heavy atoms or contain non-standard residue names.

WORKFLOW POSITION

Last step of the cleaning/preparation pipeline. Output is a relaxed PDB ready for production MD setup or coarse-graining.

DECISION GUIDANCE

preset (default "amber14_implicit"): amber14_implicit — use for typical protein relaxation; fast, no periodic box required. Best choice for most users. amber14_explicit — use when the input already has a periodic solvent box (added externally). More accurate but slower. amber99sb_implicit — an older force field; prefer amber14_implicit unless the user specifically requests AMBER99SB. charmm36_explicit — use when downstream simulation will use CHARMM36 and explicit solvent. Call query_ff_presets() to see the full list with descriptions.

run_md (default True): Set False for a minimisation-only run, which is much faster. Use minimisation-only when: (a) the structure is already well-relaxed, (b) a quick clash-removal pass is all that is needed, or (c) compute time is limited.

restrain_backbone (default True): Keep True unless the user wants full unrestrained relaxation. Backbone restraints preserve the experimental fold; without them a very short MD run can distort secondary structure.

restraint_k (default 1000 kJ/mol/nm²): Reduce to 100–200 for softer restraints that allow more backbone movement. Increase to 5000 for near-rigid backbone relaxation of side-chains only.

production_steps (default 25 000 ≈ 100 ps at 4 fs): Sufficient for side-chain relaxation and removal of clashes introduced by adding missing atoms. Increase to 250 000 (1 ns) for more thorough equilibration — note this takes substantially longer on CPU.

temperature (default 300 K): Use 300 K for room-temperature simulation. Some crystallographers prefer 277 K to match cryo conditions.

OUTPUT — WHAT TO CHECK

energy_initial_kJ_mol vs energy_final_kJ_mol: A drop of 10³–10⁶ kJ/mol after minimisation is normal for a raw crystal structure. If the final energy is still very large (> −10 000 kJ/mol for a 500-residue protein), the structure may have unresolved clashes — report to the user and suggest checking with query_pdb_structure. energy_post_md_kJ_mol: Should be more negative than energy_post_min_kJ_mol. If it is more positive, MD is diverging — reduce production_steps or timestep.

List available force-field presets for relax_pdb_structure.

WHEN TO USE

Call before relax_pdb_structure when you are unsure which preset to use or want to present the user with options.

Returns: dict mapping preset name → description string.

Return a summary of all tool calls and LLM decisions made in this session.

WHEN TO USE

The report is written to a Markdown file automatically after every tool call — you do not need to call this to produce the file. Call it when you want to:

• Tell the user where their report file is located.

• Optionally copy the report to a different path via save_to.

• Read the markdown string directly (e.g. to summarise it for the user).

Clear the session workflow report and start a fresh record.

WHEN TO USE

Call at the start of a new structure-preparation task when you want a clean report that covers only the current structure, not any previous work done in the same server session. Each reset starts a new timestamped report file.