Updated docs

Author: cmaglie

docs/package_index_json-specification.md

@@ -177,17 +177,6 @@ The other fields are:
   macOS you can use the command `shasum -a 256 filename` to generate SHA-256 checksums. There are free options for
   Windows, including md5deep. There are also online utilities for generating checksums.
 
-##### How a tool's path is determined in platform.txt
-
-When the IDE needs a tool, it downloads the corresponding archive file and unpacks the content into a private folder
-that can be referenced from `platform.txt` using one of the following properties:
-
-- `{runtime.tools.TOOLNAME-VERSION.path}`
-- `{runtime.tools.TOOLNAME.path}`
-
-For example, to obtain the avr-gcc 4.8.1 folder we can use `{runtime.tools.avr-gcc-4.8.1-arduino5.path}` or
-`{runtime.tools.avr-gcc.path}`.
-
 ### Platforms definitions
 
 Finally, let's see how `PLATFORMS` are made.
@@ -271,6 +260,32 @@ rules Arduino IDE follows for parsing versions
 Note: if you miss a bracket in the JSON index, then add the URL to your Preferences, and open Boards Manager it can
 cause the Arduino IDE to no longer load until you have deleted the file from your arduino15 folder.
 
+#### How a tool's path is determined in platform.txt
+
+When the IDE needs a tool, it downloads the corresponding archive file and unpacks the content into a private folder
+that can be referenced from `platform.txt` using one of the following properties:
+
+- `{runtime.tools.TOOLNAME-VERSION.path}`
+- `{runtime.tools.TOOLNAME.path}`
+
+For example, to obtain the avr-gcc 4.8.1 folder we can use `{runtime.tools.avr-gcc-4.8.1.path}` or
+`{runtime.tools.avr-gcc.path}`.
+
+In general the same tool may be provided by different platforms (for example the Arduino AVR platform may provide an
+`arduino:avr-gcc` and another 3rd party platform may provide their own `3rdparty:avr-gcc`). The rules to disambiguate
+are as follows:
+
+- The property `{runtime.tools.TOOLNAME.path}` points, in order of priority, to:
+
+  1. the tool, version and packager specified via `toolsDependencies` in the `package_index.json`
+  1. the highest version of the tool provided by the packager of the current platform
+  1. the highest version of the tool provided by any other packager (in case of tie, the first packager in alphabetical
+     order wins)
+
+- The property `{runtime.tools.TOOLNAME-VERSION.path}` points, in order of priority, to:
+  1. the tool and version provided by the packager of the current platform
+  1. the tool and version provided by any other packager (in case of tie, the first packager in alphabetical order wins)
+
 ### Example JSON index file
 
 ```json

docs/platform-specification.md

@@ -765,14 +765,18 @@ tools.avrdude.config.path={path}/etc/avrdude.conf
 tools.avrdude.upload.pattern="{cmd.path}" "-C{config.path}" -p{build.mcu} -c{upload.port.protocol} -P{upload.port.address} -b{upload.speed} -D "-Uflash:w:{build.path}/{build.project_name}.hex:i"
 ```
 
-A **{runtime.tools.TOOL_NAME.path}** and **{runtime.tools.TOOL_NAME-TOOL_VERSION.path}** property is generated for the
-tools of Arduino AVR Boards and any other platform installed via Boards Manager. **{runtime.tools.TOOL_NAME.path}**
-points to the latest version of the tool available.
-
 The tool configuration properties are available globally without the prefix. For example, the **tools.avrdude.cmd.path**
 property can be used as **{cmd.path}** inside the recipe, and the same happens for all the other avrdude configuration
 variables.
 
+### How to retrieve tools path via `{runtime.tools.*}` properties
+
+A **{runtime.tools.TOOLNAME.path}** and **{runtime.tools.TOOLNAME-TOOLVERSION.path}** property is generated for the
+tools provided by the current platform and for any other platform installed via Boards Manager.
+
+See [`{runtime.tools.*.path}` rules](package_index_json-specification.md#how-a-tools-path-is-determined-in-platformtxt)
+for details on how the runtime properties are determined.
+
 ### Environment variables
 
 All the tools launched to compile or upload a sketch will have the following environment variable set: