The $ issue is an edge case of course, but I agree that either the core name of the variable should not be able to start with an $ or you have a situation where it is not completely clear whether cid, $cid and $$cid refer to the same variable or not. Maybe the following change is enough to clarify this:

Provided query parameters does not have to be MUST NOT be prefixed with the $ sign. Instead, the server will have to (whenever necessary) add the prefix or format queries as valid AQL queries.

OK, I agree with the second. I still don’t like the personification of the server (it “decided”), but I can accept it.

I now understand the part of the text to which the third bullet point relates. The thing is, I don’t consider the dollar sign to be a part of the name of the parameter anyway, and our implementation actually strips the dollar sign when resolving the parameter. For example, if the AQL contains c/uid/value=$cid, we consider cid to be the parameter name and if you were to pass $cid as the key when assigning values to parameters, its value would not be substituted in place of $cid in the query. You could in principle have another placeholder in the query, $$cid, which would resolve to $cid’s value. Is there any other part of the spec that allows for the dollar sign to be either present or absent?

For the seconnd , i need also to admit that i thoughtthe api+aql works as i described: two separate process, and if internal aql execution takes longer than expected, than api responds error while the aql is stopped gracefully in parallel ... after all, if you really think my text is incorrect, i will change it, but i dont want to mention”query”, rather keep it generic, related to request

The second i’m not sure if we should change it, because i think my text is suitable also for the future, for non-query related timeouts.
For the third I removed the last part of the sentence - i thought that will fix it, but it looks like is not ...? The idea was that as client you don’t have to use $ to prefix params, but the server will have to add them when it executes the aql. I wanted to have explanation about why params are used with $ in the aql, but as client you have to name and address param without that sign. How can I explain it better?

If I'm not mistaken, only the 2nd and 3rd bullet point remain unsolved.