diff --git a/ocaml-lsp-server/docs/ocamllsp/merlinCallCompatible-specs.md b/ocaml-lsp-server/docs/ocamllsp/merlinCallCompatible-specs.md
index dee76e5e6..dea038003 100644
--- a/ocaml-lsp-server/docs/ocamllsp/merlinCallCompatible-specs.md
+++ b/ocaml-lsp-server/docs/ocamllsp/merlinCallCompatible-specs.md
@@ -10,14 +10,15 @@ clients capable of fallbacking on Merlin in the event of a missing feature.
 
 ### Why this custom request needed
 
-A temporary solution to ensure that LSP can be used as a primary front-end as
-quickly as possible. The interest in this query will diminish as iterations
-attempt to achieve parity of functionality with `ocamlmerlin`.
+It allows editor plugin to communicate with the ocaml-lsp-server using the
+merlin protocol, it will be useful for text-based editors that want to preserve
+the classic Merlin UI while using ocaml-lsp-server. (It is a temporary solution
+that will progressively be replaced by tailored custom requests filling the gaps
+in the protocol)
 
 ## Client capability
 
-nothing that should be noted. But each Merlin command should be handled
-specifically by customers.
+Here is no client capability relative to this request
 
 ## Server capability
 
@@ -45,6 +46,10 @@ property type: `boolean`
 - `resultAsSexp`: a flag indicating whether the result should be returned in
   SEXP (`true`) or JSON (`false`), by default: `false`
 
+For an exhaustive description of what the query returns, please refer to the
+[Merlin
+protocol](https://github.com/ocaml/merlin/blob/master/doc/dev/PROTOCOL.md)
+
 ## Response
 
 ```json
@@ -57,8 +62,3 @@ property type: `boolean`
 - `resultAsSexp`: `true` if the command was invoked with the `resultAsSexp` flag,
   `false` otherwise
 - `result`: the result in string (in JSON or SEXP)
-
-
-If Merlin produces an error, it will be described in the same way as the binary
-in the result. If parameters are badly formed (or missing) or if the command
-invoked does not exist in Merlin, invoking the request throws an exception.