diff --git a/README.md b/README.md
index e92bcfb713aee2411935eb141441d189059b62f8..79d0ef19e33702b7df7cfb8ff977f33807bd4549 100644
--- a/README.md
+++ b/README.md
@@ -33,3 +33,44 @@ This script will download the current edugain metadata aggregate XML and parse a
 identity providers found in order to derive a list of Organization names, domains and 
 security contacts in CSV format. This list will be printed to stdout.
 
+## Entities Details
+
+Script: `entity_details.py`
+
+This script will print out some details about a single entity or a list of entities 
+passed as a list of entityIDs.
+
+CSV Format:
+
+```
+entityID,FederationName,RegistrationAuthority,OrganizationName,TechnicalContact,SupportContact,AdministrativeContact
+```
+
+Usage:
+
+```
+usage: entity_details.py [-h] [-e E] [-f F] [-u U] [ENTITYID]
+
+Show detailed information about an eduGAIN entity.
+
+positional arguments:
+  ENTITYID    entityID of the entity to look up
+
+options:
+  -h, --help  show this help message and exit
+  -e E        load entityIDs from file E
+  -f F        load metadata from file F
+  -u U        download metadata from url U (default to https://mds.edugain.org/edugain-v2.xml)
+
+Examples
+
+- Retrieve details about a single entity using eduGAIN metadata:
+
+./entity_details.py https://idp.dir.garr.it/idp/shibboleth
+
+- Retrieve details for a list of idps using a local metadata file:
+
+./entity_details.py -e idp_list -f edugain-v2.xml
+```
+
+