feat(tools): add usage_guide tool and tighten tool descriptions

- New usage_guide tool (no params) returns an embedded guide for the LLM:
  workflow, token-saving rules, output notation ($ref/required/depth),
  and concrete example call sequences. Lets the server self-document when
  the client lacks CLAUDE.md/system-prompt context.
- Embed the guide via go:embed (internal/tools/llm_guide.md).
- Shorten all tool descriptions (~40% less) to reduce fixed per-request
  cost; get_endpoint/get_schema now explain $ref(Name) and resolve_depth.
- Update README: tools table, LLM Context Guide, design decisions.

Author: hnkatze

README.md

@@ -29,13 +29,14 @@ All output is **token-optimized by default** using TOON format (~40% fewer token
 | `fetch_spec` | Download and cache a spec. Returns title, version, endpoint/tag/schema counts. Supports `refresh=true`. |
 | `analyze_tags` | Tag summary with endpoint counts and method breakdown. **Start here** to understand the API. |
 | `list_endpoints` | List endpoints with filters (tag, method, path pattern). Auto-limited to 50 results. |
-| `get_endpoint` | Full detail for one endpoint — params, request body, responses, resolved schemas. |
-| `get_schema` | Get a named schema with all nested `$ref` fully resolved. |
+| `get_endpoint` | Full detail for one endpoint — params, request body, responses, resolved schemas (field descriptions inline; repeats shown as `$ref(Name)`). |
+| `get_schema` | Get a named schema with nested `$ref` resolved. Use to expand a `$ref(Name)` seen in `get_endpoint`. |
 | `search_spec` | Full-text search across paths, summaries, operation IDs, parameters, and body properties. Auto-limited to 50. |
 | `diff_endpoints` | Compare two spec versions. Shows added, removed, and changed endpoints. |
 | `spec_status` | Check cache status (memory/disk), fingerprint, age, ETag. No HTTP requests. |
 | `refresh_spec` | Force-refresh a cached spec. Returns change detection via fingerprint comparison. |
 | `generate_types` | Generate TypeScript interfaces or Go structs from an endpoint or named schema. |
+| `usage_guide` | Return this server's workflow, token-saving rules, output notation, and example call sequences. The LLM can call it to self-orient when it lacks setup context. |
 
 ### Recommended Workflow
 
@@ -54,6 +55,8 @@ All tools accept `format`: `toon` (default, compact) or `json`.
 
 `list_endpoints` and `search_spec` also accept `limit` (default: 50, 0 = unlimited).
 
+`get_endpoint` and `get_schema` accept `resolve_depth` (0-10, default: 3). Raise it for deeply nested models; lower it (or 0 = names only) to cut tokens further.
+
 ## Installation
 
 ### Option 1: Go Install (requires Go 1.25+)
@@ -195,11 +198,15 @@ When working with external APIs via swagger-mcp:
 - If the API spec has changed, use `refresh_spec` to get fresh data
 - Default output is TOON format (compact, token-efficient) — use format=json only when needed
 - Use `generate_types` with language=typescript or language=go instead of manually translating schemas
+- Schemas show field descriptions inline (`field*: type — description`); a `*` marks a required field
+- A repeated schema appears once, then as `$ref(Name)` — call `get_schema Name` only if you need its fields expanded
+- Schemas resolve 3 levels deep by default; pass `resolve_depth` up to 10 for deeper models
 
 ### Anti-patterns
 - Don't call `list_endpoints` without filters on large APIs (wastes tokens)
 - Don't call `get_endpoint` for every endpoint — narrow down with tags/search first
 - Don't re-fetch specs that are already cached — use `spec_status` to check
+- Don't expand every `$ref(Name)` — only fetch the ones whose fields you actually need
 ```
 
 For **Cursor**, add the same content to `.cursorrules`. For **Windsurf** or other MCP clients, add it to your system prompt or project instructions file.
@@ -344,10 +351,12 @@ internal/
 ### Key Design Decisions
 
 - **Token-first defaults** — TOON format + auto-limits minimize LLM token consumption
+- **Per-endpoint `$ref` dedup** — a schema reused across responses (e.g. a shared error envelope) is expanded once, then referenced as `$ref(Name)`; cuts ~60% of tokens on real-world specs without losing meaning
+- **Description-forward schemas** — field descriptions are surfaced inline (`field*: type — description`) while noisy `example`/`default` payloads are dropped, so the model gets signal, not bulk
 - **Guided tool descriptions** — tool descriptions steer LLMs toward efficient filter-first workflows
 - **Two-level cache** — memory + disk with HTTP conditional requests for instant cross-session access
 - **kin-openapi** for parsing — handles OpenAPI 2.0/3.x with automatic `$ref` resolution
-- **Recursive `$ref` resolution** with depth limit (10) and circular reference protection
+- **Recursive `$ref` resolution** with a low default depth (3, override up to 10) and circular reference protection
 - **stdio transport** — universal compatibility with MCP clients
 - **Zero configuration** — sensible defaults, env vars for optional tuning
 

internal/tools/llm_guide.md

@@ -0,0 +1,81 @@
+# swagger-mcp — usage guide
+
+This server lets you explore an OpenAPI/Swagger spec without loading the whole
+document into context. It is built to minimize tokens: responses are compact
+(TOON), lists are auto-limited, and repeated schemas are de-duplicated. Follow
+the workflow below to stay efficient.
+
+## Workflow
+
+1. `fetch_spec` — once per spec URL. Returns title/version/counts. Establishes
+   the cache so later calls are instant.
+2. `analyze_tags` — **always start here**. Maps the API into tags with endpoint
+   counts so you know where to look.
+3. `list_endpoints` — filter by `tag` (preferred), `method`, or `path_pattern`.
+   Never browse unfiltered on a large API.
+4. `get_endpoint` — full detail for one endpoint: params, request body,
+   responses, and resolved schemas.
+5. `get_schema` — only to expand a `$ref(Name)` you saw in `get_endpoint` and
+   whose fields you actually need.
+6. `generate_types` — emit ready-to-paste TypeScript interfaces or Go structs
+   instead of translating schemas by hand.
+
+`search_spec` is the shortcut when you already know a keyword (it searches
+paths, summaries, operation IDs, params, and body field names).
+
+## Reading the output (TOON)
+
+- Endpoint list: `METHOD /path — summary [tag1, tag2]`, one per line.
+- Schema fields: `field: type` — a trailing `*` marks a **required** field, and
+  `— text` after the type is the field's description. Example:
+  `email*: string(email) — primary contact email`.
+- `$ref(Name)` means that schema was already shown once in this response (or is
+  shared across responses). Don't re-expand it unless you need its fields — and
+  if you do, call `get_schema Name`.
+- Schemas resolve **3 levels deep by default**. Pass `resolve_depth` (0–10) to
+  go deeper on nested models, or `0` for names-only (cheapest).
+
+## Token-efficiency rules
+
+- Filter before listing. `analyze_tags` → filtered `list_endpoints` beats one
+  unfiltered dump by ~30×.
+- Reuse the cache. Don't re-`fetch_spec` a URL you already loaded; check
+  `spec_status` if unsure.
+- Default format is TOON (compact). Only pass `format=json` when a tool consumer
+  needs structured JSON.
+- Lower `resolve_depth` (or 0) when you only need field names, not nested shapes.
+
+## Example sequences
+
+**"What can this API do with employees?"**
+```
+analyze_tags(url)                          → see an "Employee" tag, 40 endpoints
+list_endpoints(url, tag="Employee")        → the 40 endpoints, one line each
+get_endpoint(url, "POST", "/api/v1/Employee")  → full request/response shape
+```
+
+**"I need to call the create-user endpoint."**
+```
+search_spec(url, query="create user")      → ranked matches
+get_endpoint(url, "POST", "/users")        → params + body + responses
+get_schema(url, "CreateUserDto")           → only if a $ref(CreateUserDto) needs expanding
+```
+
+**"Give me the TypeScript types for the orders response."**
+```
+generate_types(url, method="GET", path="/orders", language="typescript")
+```
+
+**"Did the spec change since last time?"**
+```
+refresh_spec(url)   → reports changed/unchanged via fingerprint, plus a fresh summary
+```
+
+## Anti-patterns
+
+- Don't `list_endpoints` without filters on a large API — it wastes tokens.
+- Don't `get_endpoint` every endpoint to "look around" — narrow with tags/search.
+- Don't expand every `$ref(Name)` — only the ones whose fields you actually need.
+- Don't re-fetch a cached spec — use `spec_status` to check first.
+- Don't raise `resolve_depth` to 10 by reflex — the default of 3 is enough for
+  most models, and the dedup keeps shared schemas from repeating anyway.