Improve documentation output for AI consumption #11

New issue

Open

opened 2026-01-05 17:05:59 +00:00 by mprihoda · 0 comments

mprihoda commented

2026-01-05 17:05:59 +00:00

(Migrated from github.com)

Problem

The current get_documentation tool returns raw HTML from Javadoc/Scaladoc JARs. This is problematic for AI assistants because:

Large output size - A single class like zio.ZIO returns 665KB of HTML
HTML is for browsers, not AI - Requires parsing HTML to extract useful information
No method-level queries - Must fetch entire class documentation to find one method

Proposed Enhancements

1. Return plain text or markdown instead of HTML

Convert the HTML documentation to a more AI-friendly format that preserves structure without markup noise.

2. Support querying specific methods

Allow targeting specific members, e.g.:

{
  "coordinates": "dev.zio::zio:2.1.14",
  "className": "zio.ZIO",
  "member": "zip"
}

3. Return structured data

Pre-extract method signatures and descriptions into structured JSON:

{
  "className": "zio.ZIO",
  "methods": [
    {
      "name": "zip",
      "signature": "def zip[R1 <: R, E1 >: E, B](that: => ZIO[R1, E1, B]): ZIO[R1, E1, (A, B)]",
      "description": "A named alias for <*>."
    }
  ]
}

Benefits

Faster responses (smaller payloads)
Direct answers without HTML parsing
Better token efficiency for AI assistants

## Problem The current `get_documentation` tool returns raw HTML from Javadoc/Scaladoc JARs. This is problematic for AI assistants because: 1. **Large output size** - A single class like `zio.ZIO` returns 665KB of HTML 2. **HTML is for browsers, not AI** - Requires parsing HTML to extract useful information 3. **No method-level queries** - Must fetch entire class documentation to find one method ## Proposed Enhancements ### 1. Return plain text or markdown instead of HTML Convert the HTML documentation to a more AI-friendly format that preserves structure without markup noise. ### 2. Support querying specific methods Allow targeting specific members, e.g.: ```json { "coordinates": "dev.zio::zio:2.1.14", "className": "zio.ZIO", "member": "zip" } ``` ### 3. Return structured data Pre-extract method signatures and descriptions into structured JSON: ```json { "className": "zio.ZIO", "methods": [ { "name": "zip", "signature": "def zip[R1 <: R, E1 >: E, B](that: => ZIO[R1, E1, B]): ZIO[R1, E1, (A, B)]", "description": "A named alias for <*>." } ] } ``` ## Benefits - Faster responses (smaller payloads) - Direct answers without HTML parsing - Better token efficiency for AI assistants