molclaw-foldx-tool

FoldX Protein Stability & Mutation Analysis

Note:

• Local files are not directly accessible by the server. Please upload them to the server using molclaw-file-transfer before execution.
• For PDB file inputs, it is recommended to preprocess them using molclaw-pdbfixer before execution.
• Please refer to skill molclaw-scp-server to complete tool invocation.

Critical Prerequisite

MANDATORY: Run mode=repairpdb on every PDB before any other FoldX mode. FoldX optimizes side-chain rotamers against its own empirical energy function; unrepaired structures produce unreliable energy values. This is independent of molclaw-pdbfixer — even pdbfixer-repaired structures need FoldX RepairPDB. The output *_Repair.pdb is the ONLY acceptable input for subsequent FoldX modes.

• For PDB file inputs, it is recommended to preprocess them using molclaw-pdbfixer before FoldX RepairPDB.

When To Use This Skill

Scenario	Use FoldX	Use other tool instead
Evaluate protein intrinsic stability (ΔG)	✅ stability	—
Predict effect of known mutations (ΔΔG)	✅ buildmodel	—
Protein–protein interface energy (fast, minutes)	✅ analysecomplex	MMPBSA (precise, hours)
Identify interface hotspot residues	✅ alascan with chains	MMPBSA per-residue decomposition (precise)
Saturating mutagenesis scan at specific sites	✅ positionscan	—
Affinity maturation on complex interface	✅ pssm	—
Per-residue energy decomposition	✅ sequencedetail	interaction-visualizer (geometry level)
Small-molecule binding free energy	❌	Boltz-2, MMPBSA
MD trajectory dynamics	❌	GROMACS, OpenMM
Batch docking pose evaluation	❌	EquiScore, ProLIF

Unified Tool Interface

All 8 modes are accessed through a single tool foldx_tool with a mode parameter. The full parameter set is:

Run FoldX energy evaluation and mutation-scanning workflows for protein stability
or complex-interface screening.
Args:
    mode (str): FoldX command mode, REQUIRED. One of: repairpdb, stability,
        buildmodel, analysecomplex, alascan, positionscan, pssm, sequencedetail.
    pdb_path (str): Input PDB file path, REQUIRED for all modes.
    chains (str|None): Complex chain definition, e.g. 'A,B' or 'HL,A'.
        REQUIRED for analysecomplex and pssm.
        OPTIONAL for alascan (enables complex-mode interface scanning).
        Ignored by other modes. Default: None.
    positions (str|None): Comma-separated mutation position tokens.
        Format: OrigAA(1-letter) + ChainID + ResNum + TargetAA.
        REQUIRED for positionscan and pssm. Default: None.
    mutant_file (str|None): Path to FoldX-format mutation list file.
        REQUIRED for buildmodel. Default: None.
    number_of_runs (int): Independent repeats for buildmodel (1-100). Default: 5.
    water (str): Water handling: CRYSTAL|PREDICT|NONE|COMPARE. Default: CRYSTAL.
    pdb_hydrogens (bool): Read hydrogens from PDB. Default: False.
    dry_run (bool): Return planned command without execution. Default: False.
    timeout (int): Maximum execution time in seconds. Default: 7200.
Return:
    status (str): success | error | partial_success
    msg (str): Execution summary or error message
    mode (str): Normalized FoldX command mode
    output_dir (str|None): Run directory path
    foldx_command (str|None): Executed or planned command line
    pdb_file (str|None): Input PDB filename in output_dir
    key_files (dict): Key output files relative to output_dir
    metrics (dict): return_code, generated_file_count, and mode-specific values
        (total_energy, mean_ddg, ddg_values, interaction_energy, hotspot_count)
    stderr_tail (str, only on error): Last portion of FoldX stderr for diagnostics