diff --git a/src/content/code/language-support/scala/client/caliban.md b/src/content/code/language-support/scala/client/caliban.md
index 6713604fd..4ad957d62 100644
--- a/src/content/code/language-support/scala/client/caliban.md
+++ b/src/content/code/language-support/scala/client/caliban.md
@@ -1,6 +1,21 @@
 ---
 name: Caliban
-description: Functional GraphQL library for Scala, with client code generation and type-safe queries.
+description: Caliban is a functional library for building GraphQL servers and clients in Scala. It offers with client code generation and type-safe queries.
 url: https://ghostdogpr.github.io/caliban/
 github: ghostdogpr/caliban
 ---
+
+An example of defining a GraphQL query and running it with `caliban`:
+
+```scala
+// define your query using Scala
+val query: SelectionBuilder[RootQuery, List[CharacterView]] =
+  Query.characters {
+    (Character.name ~ Character.nicknames ~ Character.origin)
+      .mapN(CharacterView)
+  }
+
+import sttp.client3._
+// run the query and get the result already parsed into a case class
+val result = query.toRequest(uri"http://someUrl").send(HttpClientSyncBackend()).body
+```
diff --git a/src/content/code/language-support/scala/server/caliban.md b/src/content/code/language-support/scala/server/caliban.md
index 83409d0a0..404ccfb6c 100644
--- a/src/content/code/language-support/scala/server/caliban.md
+++ b/src/content/code/language-support/scala/server/caliban.md
@@ -1,30 +1,26 @@
 ---
 name: Caliban
-description: Caliban is a purely functional library for building GraphQL servers and clients in Scala
+description: Caliban is a functional library for building GraphQL servers and clients in Scala. It offers minimal boilerplate and excellent interoperability.
 url: https://ghostdogpr.github.io/caliban/
 github: ghostdogpr/caliban
 ---
 
-An example of a GraphQL schema and query with `caliban`:
+An example of a simple GraphQL schema and query with `caliban`:
 
 ```scala
-import caliban.GraphQL.graphQL
-import caliban.RootResolver
-
-case class Character(name: String, age: Int)
-
-def getCharacters(): List[Character] = ???
+import caliban._
+import caliban.schema.Schema.auto._
 
 // schema
-case class Queries(characters: List[Character])
+case class Query(hello: String)
 
 // resolver
-val queries = Queries(getCharacters)
+val resolver = RootResolver(Query("Hello world!"))
 
-val api = graphQL(RootResolver(queries))
+val api = graphQL(resolver)
 
 for {
   interpreter <- api.interpreter
-  result      <- interpreter.execute("{ characters { name } }")
+  result      <- interpreter.execute("{ hello }")
 } yield result
 ```