These observations come out of issue #3007 :
If a tool module chooses to add command-line options which only it will consume, the behavior isn't always what you might expect. As of this writing, one internal tool module, install.py, does this. It uses AddOption in its generate function, which means the option is only added to SCons if the tool's generate is actually called.

• asking for --help will not go through a code path that calls the tool's generate, so the option's help text never shows up.
• there are various circumstances under which the option can be missing, leading to confusing errors when an option you may have documented for your users fails. For example, with the install tool, calling scons --install-sandbox=zzz when the SConstruct doesn't have an install in it errors out:

  SCons Error: no such option: --install-sandbox   
  

I don't have a general solution for the problem at the moment. Some questions to ponder:

• Is AddOption the right way to add an option in a tool, or should some more internal method be used?
• Should tools in fact ever do this? Is it different for included-in-scons tools vs. user-written tools?
• is there guidance we can give to tool writers to help get it right?