diff --git a/samples/README.md b/samples/README.md
index 9c576257..0ad41c69 100644
--- a/samples/README.md
+++ b/samples/README.md
@@ -1 +1,19 @@
-GenerativeAI sample snippets for Android in Kotlin and Java
+# Gemini API Android SDK sample code
+
+This directory contains sample code for key features of the SDK, organised by high level feature.
+
+These samples are embedded in parts of the [documentation](https://ai.google.dev), most notably in the [API reference](https://ai.google.dev/api).
+
+## Contents
+
+| Kotlin | Java | Description |
+| ------ | ---- | ----------- |
+| [chat.kt](src/main/java/com/google/ai/client/generative/samples/chat.kt) | [chat.java](src/main/java/com/google/ai/client/generative/samples/java/chat.java) | Multi-turn chat conversations |
+| [code_execution.kt](src/main/java/com/google/ai/client/generative/samples/code_execution.kt) | [code_execution.java](src/main/java/com/google/ai/client/generative/samples/java/code_execution.java) | Executing code |
+| [configure_model_parameters.kt](src/main/java/com/google/ai/client/generative/samples/configure_model_parameters.kt) | [configure_model_parameters.java](src/main/java/com/google/ai/client/generative/samples/java/configure_model_parameters.java) | Setting model parameters |
+| [controlled_generation.kt](src/main/java/com/google/ai/client/generative/samples/controlled_generation.kt) | [controlled_generation.java](src/main/java/com/google/ai/client/generative/samples/java/controlled_generation.java) | Generating content with output constraints (e.g. JSON mode) |
+| [count_tokens.kt](src/main/java/com/google/ai/client/generative/samples/count_tokens.kt) | [count_tokens.java](src/main/java/com/google/ai/client/generative/samples/java/count_tokens.java) | Counting input and output tokens |
+| [function_calling.kt](src/main/java/com/google/ai/client/generative/samples/function_calling.kt) | [function_calling.java](src/main/java/com/google/ai/client/generative/samples/java/function_calling.java) | Using function calling |
+| [safety_settings.kt](src/main/java/com/google/ai/client/generative/samples/safety_settings.kt) | [safety_settings.java](src/main/java/com/google/ai/client/generative/samples/java/safety_settings.java) | Setting and using safety controls |
+| [system_instruction.kt](src/main/java/com/google/ai/client/generative/samples/system_instruction.kt) | [system_instruction.java](src/main/java/com/google/ai/client/generative/samples/java/system_instruction.java) | Setting system instructions |
+| [text_generation.kt](src/main/java/com/google/ai/client/generative/samples/text_generation.kt) | [text_generation.java](src/main/java/com/google/ai/client/generative/samples/java/text_generation.java) | Generating text |