Get compact class summary (token-efficient docs) #15

New issue

Open

opened 2026-01-05 21:13:44 +00:00 by mprihoda · 0 comments

mprihoda commented

2026-01-05 21:13:44 +00:00

(Migrated from github.com)

Problem

Full Javadoc/Scaladoc is verbose and consumes many tokens. Agent often just needs:

What is this class for?
What are the key methods?
How do I create an instance?

Proposed Solution

New Tool: `get_class_summary`

{
  "name": "get_class_summary",
  "description": "Get a compact summary of a class",
  "input": {
    "coordinates": "Maven/Coursier coordinates",
    "className": "Fully qualified class name",
    "scalaVersion": "optional"
  }
}

Example:

get_class_summary("org.typelevel::cats-effect:3.5.4", "cats.effect.IO")

Returns:

## cats.effect.IO[+A]

**Purpose:** Primary effect type for cats-effect. Represents a suspended computation that may perform side effects.

**Type:** sealed abstract class

**Constructors:**
- `IO.pure(a: A): IO[A]` - Lift pure value
- `IO.delay(thunk: => A): IO[A]` - Suspend side effect
- `IO.async[A](k: ...): IO[A]` - Async callback

**Key Methods:**
- `flatMap[B](f: A => IO[B]): IO[B]` - Sequential composition
- `map[B](f: A => B): IO[B]` - Transform result
- `attempt: IO[Either[Throwable, A]]` - Capture errors
- `handleErrorWith(f: Throwable => IO[A]): IO[A]` - Error recovery

**Common Patterns:**
- Use `IOApp` for main entry point
- Use `Resource` for acquire/release
- Call `.unsafeRunSync()` only in tests

**See Also:** IOApp, Resource, Fiber

Implementation

Parse Javadoc HTML for class description + method summaries
Use TASTy for Scala 3 (more structured)
AI summarization as fallback (optional)
Cache summaries (they're expensive to generate)

Value for Agent

10x fewer tokens than full docs
Immediately actionable information
"Cheat sheet" level of detail

Acceptance Criteria

Extract class description (first paragraph)
List constructors/factory methods
List key methods with signatures
Keep response under 500 tokens typically
Include "See Also" for related types

## Problem Full Javadoc/Scaladoc is verbose and consumes many tokens. Agent often just needs: - What is this class for? - What are the key methods? - How do I create an instance? ## Proposed Solution ### New Tool: `get_class_summary` ```json { "name": "get_class_summary", "description": "Get a compact summary of a class", "input": { "coordinates": "Maven/Coursier coordinates", "className": "Fully qualified class name", "scalaVersion": "optional" } } ``` **Example:** ``` get_class_summary("org.typelevel::cats-effect:3.5.4", "cats.effect.IO") ``` **Returns:** ```markdown ## cats.effect.IO[+A] **Purpose:** Primary effect type for cats-effect. Represents a suspended computation that may perform side effects. **Type:** sealed abstract class **Constructors:** - `IO.pure(a: A): IO[A]` - Lift pure value - `IO.delay(thunk: => A): IO[A]` - Suspend side effect - `IO.async[A](k: ...): IO[A]` - Async callback **Key Methods:** - `flatMap[B](f: A => IO[B]): IO[B]` - Sequential composition - `map[B](f: A => B): IO[B]` - Transform result - `attempt: IO[Either[Throwable, A]]` - Capture errors - `handleErrorWith(f: Throwable => IO[A]): IO[A]` - Error recovery **Common Patterns:** - Use `IOApp` for main entry point - Use `Resource` for acquire/release - Call `.unsafeRunSync()` only in tests **See Also:** IOApp, Resource, Fiber ``` ## Implementation - Parse Javadoc HTML for class description + method summaries - Use TASTy for Scala 3 (more structured) - AI summarization as fallback (optional) - Cache summaries (they're expensive to generate) ## Value for Agent - 10x fewer tokens than full docs - Immediately actionable information - "Cheat sheet" level of detail ## Acceptance Criteria - [ ] Extract class description (first paragraph) - [ ] List constructors/factory methods - [ ] List key methods with signatures - [ ] Keep response under 500 tokens typically - [ ] Include "See Also" for related types