@@ -12,8 +12,17 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Encapsulates a handler method and its target bean.
- * Supports both eager instance and lazy factory-based construction.
+ * One handler method that {@link AcpAgentSupport} found: the bean it is called on, the
+ * {@link Method}, and the ACP method it answers, such as {@code session/prompt} or an extension
+ * method name. The builder creates one for each handler method when a bean is given to it, and the
+ * runtime calls {@link #invoke} for each request. Applications do not need this class, and no
+ * extension point receives it: an interceptor or argument resolver learns what is called from
+ * {@link com.agentclientprotocol.sdk.agent.support.invocation.AcpInvocationContext#getAcpMethod()
+ * AcpInvocationContext.getAcpMethod()} and {@link AcpMethodParameter#getMethod()}.
+ *
+ * <p>The constructor makes the method accessible ({@link Method#setAccessible(boolean)}), so
+ * handler methods of any visibility can be called; it fails if the method's module does not open
+ * its package to the SDK. Instances do not change after construction.
  *
  * @author Mark Pollack
  * @since 1.0.0
@@ -31,20 +40,22 @@ public final class AcpHandlerMethod {
 	private final AcpMethodParameter returnType;
 
 	/**
-	 * Create a handler method with an eager bean instance.
-	 * @param bean the target bean instance
-	 * @param method the method to invoke
-	 * @param acpMethod the ACP method name (e.g., "initialize", "session/prompt")
+	 * Creates a handler method that calls {@code method} on {@code bean}.
+	 * @param bean the object the method is called on
+	 * @param method the handler method, made accessible here
+	 * @param acpMethod the ACP method it answers, such as {@code "initialize"} or
+	 * {@code "session/prompt"}
 	 */
 	public AcpHandlerMethod(Object bean, Method method, String acpMethod) {
 		this(() -> bean, method, acpMethod);
 	}
 
 	/**
-	 * Create a handler method with a lazy bean supplier.
-	 * @param beanSupplier supplier for the target bean
-	 * @param method the method to invoke
-	 * @param acpMethod the ACP method name
+	 * Creates a handler method that calls {@code method} on the object {@code beanSupplier} gives.
+	 * The supplier is asked on every call, so it may return a different object each time.
+	 * @param beanSupplier gives the object the method is called on
+	 * @param method the handler method, made accessible here
+	 * @param acpMethod the ACP method it answers
 	 */
 	public AcpHandlerMethod(Supplier<Object> beanSupplier, Method method, String acpMethod) {
 		this.beanSupplier = beanSupplier;
@@ -63,50 +74,56 @@ public AcpHandlerMethod(Supplier<Object> beanSupplier, Method method, String acp
 	}
 
 	/**
-	 * Get the target bean instance.
+	 * Returns the object the method is called on, asking the supplier if one was given.
 	 * @return the bean
 	 */
 	public Object getBean() {
 		return beanSupplier.get();
 	}
 
 	/**
-	 * Get the method to invoke.
+	 * Returns the handler method.
 	 * @return the method
 	 */
 	public Method getMethod() {
 		return method;
 	}
 
 	/**
-	 * Get the ACP method name (e.g., "initialize", "session/prompt").
+	 * Returns the ACP method this handler answers, such as {@code "initialize"},
+	 * {@code "session/prompt"} or an extension method name starting with {@code _}.
 	 * @return the ACP method name
 	 */
 	public String getAcpMethod() {
 		return acpMethod;
 	}
 
 	/**
-	 * Get the pre-computed parameter metadata.
-	 * @return array of parameter metadata
+	 * Returns the descriptions of the method's parameters, in order, made once at construction. The
+	 * array is shared: do not change it.
+	 * @return the parameter descriptions
 	 */
 	public AcpMethodParameter[] getParameters() {
 		return parameters;
 	}
 
 	/**
-	 * Get the return type metadata.
-	 * @return the return type parameter
+	 * Returns the description of the method's return type.
+	 * @return the return type description, for which {@link AcpMethodParameter#isReturnType()} is
+	 * true
 	 */
 	public AcpMethodParameter getReturnType() {
 		return returnType;
 	}
 
 	/**
-	 * Invoke the method with the given arguments.
-	 * @param args the arguments
-	 * @return the return value
-	 * @throws Exception if invocation fails
+	 * Calls the handler method on the bean with {@code args}, which must match its parameters in
+	 * number and type.
+	 * @param args the arguments, one for each parameter
+	 * @return what the method returned, or null for a {@code void} method
+	 * @throws Exception if the handler method throws: its exception, as it threw it (not wrapped in
+	 * an {@code InvocationTargetException}); an {@link Error} it throws is rethrown as is
+	 * @throws IllegalArgumentException if {@code args} do not match the method's parameters
 	 */
 	public @Nullable Object invoke(@Nullable Object[] args) throws Exception {
 		try {
 
@@ -9,11 +9,25 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Strategy interface for handling method return values and converting
- * them to protocol responses.
+ * Turns what a handler method returned into the response of its ACP method. Implement one for a
+ * return type the built-in handlers do not accept, such as another library's async type, and
+ * register it with
+ * {@link com.agentclientprotocol.sdk.agent.support.AcpAgentSupport.Builder#returnValueHandler
+ * AcpAgentSupport.Builder.returnValueHandler(..)}. The built-in handlers accept the method's
+ * response itself, {@code void} and {@code String} from a {@code @Prompt} method, a {@code Mono},
+ * {@code CompletionStage} or single-value {@code Publisher} of those, and an extension method's
+ * result.
  *
- * <p>Implementations of this interface are responsible for converting
- * handler method return values to the appropriate protocol response types.
+ * <p>For each call, the runtime uses the first handler whose {@link #supportsReturnType} returns
+ * {@code true}: custom handlers in the order they were added, then the built-in ones, so a custom
+ * handler can also replace a built-in one. A return type that a custom handler supports is not
+ * checked when the agent is built. A handler for an async type can wait for the value and pass it
+ * to a built-in handler, such as {@link StringToPromptResponseHandler} for a {@code String} from a
+ * {@code @Prompt} method.
+ *
+ * <p>Implementations must be thread-safe: one instance serves every call, from every session and
+ * connection, concurrently. {@link #handleReturnValue} runs on the call's handler thread and may
+ * block there, as the built-in handler does to wait for a {@code Mono}.
  *
  * @author Mark Pollack
  * @since 1.0.0
@@ -22,19 +36,25 @@
 public interface ReturnValueHandler {
 
 	/**
-	 * Determine whether this handler supports the given return type.
-	 * @param returnType the return type metadata
-	 * @return true if this handler can process the return type
+	 * Returns whether this handler accepts the return type. Decide from the type only: it is asked
+	 * when the agent is built and on every call.
+	 * @param returnType the handler method's return type
+	 * @return true if {@link #handleReturnValue} can turn values of it into the response
 	 */
 	boolean supportsReturnType(AcpMethodParameter returnType);
 
 	/**
-	 * Handle the return value and convert to protocol response.
-	 * @param returnValue the value returned by the handler method
-	 * @param returnType the return type metadata
-	 * @param context the invocation context
-	 * @return the protocol response
-	 * @throws ReturnValueHandlingException if handling fails
+	 * Turns {@code returnValue} into the response sent to the client. For a request, the result
+	 * must be the ACP method's response type, such as a {@code PromptResponse}; another type, or
+	 * null, is answered with an internal error ({@code -32603}). For a notification, the result is
+	 * ignored.
+	 * @param returnValue what the method returned, after the interceptors' {@code postInvoke}; null
+	 * for a {@code void} method
+	 * @param returnType the handler method's return type
+	 * @param context the call's context
+	 * @return the response
+	 * @throws ReturnValueHandlingException if the value cannot be turned into a response; the call
+	 * fails with an internal error ({@code -32603}) carrying its message
 	 */
 	@Nullable Object handleReturnValue(@Nullable Object returnValue, AcpMethodParameter returnType,
 			AcpInvocationContext context);
 
@@ -12,10 +12,15 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Composite that chains multiple return value handlers.
+ * A {@link ReturnValueHandler} that asks a list of handlers in order and uses the first that
+ * supports a return type. The annotation runtime builds one each time an agent is built, with the
+ * custom handlers first and the built-in ones after, and turns every handler method's result into
+ * its response through it. Applications register handlers on {@code AcpAgentSupport.Builder} and do
+ * not need this class.
  *
- * <p>NOTE: Unlike argument resolvers, NO caching is used here.
- * Return types vary more and caching provides less benefit.
+ * <p>Unlike {@link com.agentclientprotocol.sdk.agent.support.resolver.ArgumentResolverComposite},
+ * it remembers nothing: it asks the handlers again on every call. Handling is thread-safe once the
+ * handlers are added; adding handlers is not, so add them all before the first use.
  *
  * @author Mark Pollack
  * @since 1.0.0
@@ -25,28 +30,28 @@ public class ReturnValueHandlerComposite implements ReturnValueHandler {
 	private final List<ReturnValueHandler> handlers = new ArrayList<>();
 
 	/**
-	 * Add a handler to the chain.
-	 * @param handler the handler to add
-	 * @return this composite for chaining
+	 * Adds a handler, asked after the ones added before.
+	 * @param handler the handler, not null
+	 * @return this composite
 	 */
 	public ReturnValueHandlerComposite addHandler(ReturnValueHandler handler) {
 		this.handlers.add(handler);
 		return this;
 	}
 
 	/**
-	 * Add multiple handlers to the chain.
-	 * @param handlers the handlers to add
-	 * @return this composite for chaining
+	 * Adds handlers, in list order, asked after the ones added before.
+	 * @param handlers the handlers, none of them null
+	 * @return this composite
 	 */
 	public ReturnValueHandlerComposite addHandlers(List<ReturnValueHandler> handlers) {
 		this.handlers.addAll(handlers);
 		return this;
 	}
 
 	/**
-	 * Get the list of registered handlers.
-	 * @return unmodifiable list of handlers
+	 * Returns the handlers in the order they are asked.
+	 * @return an unmodifiable copy of the handlers
 	 */
 	public List<ReturnValueHandler> getHandlers() {
 		return List.copyOf(handlers);
@@ -57,6 +62,17 @@ public boolean supportsReturnType(AcpMethodParameter returnType) {
 		return findHandler(returnType) != null;
 	}
 
+	/**
+	 * {@inheritDoc}
+	 *
+	 * <p>Delegates to the first handler that supports the return type.
+	 * @param returnValue {@inheritDoc}
+	 * @param returnType {@inheritDoc}
+	 * @param context {@inheritDoc}
+	 * @return {@inheritDoc}
+	 * @throws ReturnValueHandlingException if no handler supports the return type, or the handler
+	 * throws it
+	 */
 	@Override
 	public @Nullable Object handleReturnValue(@Nullable Object returnValue, AcpMethodParameter returnType,
 			AcpInvocationContext context) {
 
@@ -5,25 +5,30 @@
 package com.agentclientprotocol.sdk.agent.support.handler;
 
 /**
- * Exception thrown when return value handling fails.
+ * Thrown when what a handler method returned cannot be turned into its response: no return value
+ * handler accepts the type, or the value does not suit the method, such as a {@code String}
+ * returned outside a prompt turn. The call fails, and the client receives an internal error
+ * ({@code -32603}) whose message is this exception's message, so keep secrets out of it. Building
+ * the agent rejects most unsuitable return types up front, so at run time it usually comes from a
+ * custom {@link ReturnValueHandler}, which throws it for the same purpose.
  *
  * @author Mark Pollack
  * @since 1.0.0
  */
 public class ReturnValueHandlingException extends RuntimeException {
 
 	/**
-	 * Create a new exception with a message.
-	 * @param message the error message
+	 * Creates the exception.
+	 * @param message what could not be handled, sent to the client
 	 */
 	public ReturnValueHandlingException(String message) {
 		super(message);
 	}
 
 	/**
-	 * Create a new exception with a message and cause.
-	 * @param message the error message
-	 * @param cause the underlying cause
+	 * Creates the exception with the failure that caused it.
+	 * @param message what could not be handled, sent to the client
+	 * @param cause the underlying failure
 	 */
 	public ReturnValueHandlingException(String message, Throwable cause) {
 		super(message, cause);