--- a/obisort.xml	Wed Sep 01 07:53:40 2021 +0000
+++ b/obisort.xml	Thu Oct 30 16:03:21 2025 +0000
@@ -1,9 +1,9 @@
 <tool id="obi_sort" name="obisort" version="@TOOL_VERSION@" profile="@PROFILE@">
     <description>sorts sequence records according to the value of a given attribute</description>
-    <expand macro="bio_tools"/>
     <macros>
         <import>macros.xml</import>
     </macros>
+    <expand macro="bio_tools"/>
     <expand macro="requirements"/>
     <expand macro="stdio"/>
 
@@ -11,7 +11,9 @@
         @GUNZIP_INPUT@
         obisort
         --without-progress-bar
+        #if $key:
         -k '$key'
+        #end if
         ${reverse}
         @INPUT_FORMAT@
         @OUT_FORMAT@
@@ -21,9 +23,14 @@
         @GENERATE_GALAXY_JSON@
     ]]></command>
     <inputs>
-        <param name="input" type="data" format="@INPUT_FORMATS@,txt,tabular" label="Input sequences file" />
-        <param name="key" type="text" label="key"/>
-        <param name="reverse" type="boolean" checked="false" truevalue="-r" falsevalue="" label="sorts in reverse order?" />
+        <param name="input" type="data" format="@INPUT_FORMATS@,txt,tabular" label="Input sequences file"/>
+        <param
+            name="key"
+            type="text"
+            label="Key"
+            help="This key must be encoded in your FASTA/FASTQ headers as key=value. See help (below) for more information."
+            optional="false"/>
+        <param name="reverse" type="boolean" checked="false" truevalue="-r" falsevalue="" label="Sort in reverse order?" />
         <expand macro="input_format_options_macro"/>
         <expand macro="out_format_macro"/>
     </inputs>
@@ -31,14 +38,14 @@
         <data format="auto" name="output"/>
     </outputs>
     <tests>
-        <test>
+        <test expect_num_outputs="1">
             <param name="input" value="output_obiclean_advanced.fasta" />
             <param name="key" value="count"/>
             <param name="reverse" value="False"/>
             <param name="out_format" value="fasta"/>
             <output name="output" file="output_obisort.fasta" ftype="fasta"/>
         </test>
-        <test>
+        <test expect_num_outputs="1">
             <param name="input" value="output_obiclean_advanced.fasta" />
             <param name="key" value="count"/>
             <param name="reverse" value="True"/>
@@ -56,8 +63,29 @@
 
 @OBITOOLS_LINK@
 
-        ]]>
+**Inputs:**
+
+For sorting by key, the input file must be in the
+`OBITools FASTA/FASTQ format <https://pythonhosted.org/OBITools/attributes.html>`_.
+If your file is an OBITools output, it should already be formatted correctly.
+
+For FASTA files, your headers should look like this::
 
+    >my_sequence taxid=3456; direct=True; sample=A354; this is my pretty sequence
+    ACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGT
+    GTGCTGACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTGTTT
+    AACGACGTTGCAGTACGTTGCAGT
+
+Where ``taxid``, ``direct``, and ``sample`` are keys that can be used for sorting.
+
+If your sequences don't have title, you can format the headers with a trailing semicolon like so::
+
+    >my_sequence key1=value1;
+
+For sorting OBITools output files, a list of OBITools sequence attributes are documented
+`here <https://pythonhosted.org/OBITools/attributes.html#names-reserved-for-attributes>`_.
+
+]]>
     </help>
     <expand macro="citation" />
 </tool>