molclaw-foldx-tool

FoldX Protein Stability & Mutation Analysis

Invocation

Use the exact tool name and parameter schema exposed by the current harness. Tool names in SDK examples below are raw MCP names, not model-facing aliases. Local files must be uploaded with molclaw-file-transfer before a server tool can use them. Repair PDB inputs first when the workflow requires it.

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-fix-pdb — 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-fix-pdb before FoldX RepairPDB.

When To Use This Skill

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