MCP Tools Specification

DocShark exposes 4 MCP tools following the Six-Tool Pattern and MCP best practices.

Design Principles

1. Tools are a UI for agents — designed for how an LLM thinks, not a REST API wrapper
2. Descriptions are everything — the LLM reads descriptions to decide when to use a tool
3. Pre-processed results — formatted for LLM consumption, not raw data dumps
4. Keep the set compact — avoids context rot with clear, non-overlapping purposes
5. Idempotent reads — search and list operations are safe to retry

Tool Workflow

Agent needs documentation info
         │
         ▼
  ┌──────────────┐
  │ list_libraries│ ← "What docs are indexed?"
  └──────┬───────┘
         │
         ├── Library exists ──→ search_docs ──→ get_doc_page
         │                      (80% of usage)   (deep read)
         │
         └── Not found ──────→ manage_library (action=add)
                                     │
                               manage_library (action=rename)
                                     │
                               manage_library (action=refresh)
                                     │
                               manage_library (action=remove)

search_docs

The primary tool. Full-text search across all indexed documentation.

When agents use it: Whenever they need to find information about a library, API, framework feature, or code pattern.

Example output:

## Results for "svelte transitions"

### 1. Transitions — Svelte 5 Documentation
**Source:** https://svelte.dev/docs/svelte/transition
**Section:** Built-in transitions > fade

Svelte provides several built-in transition functions:
- `fade` — fades the element in and out
- `fly` — flies the element in from a specified position

list_libraries

Discovery tool. Shows what documentation is currently indexed, how old each index is, and which libraries are stale (not crawled in 14+ days).

Example output:

## Libraries (1-4 of 4)

| Library     | URL                          | Pages | Chunks | Status  | Last Crawled        | Age    |
| ----------- | ---------------------------- | ----- | ------ | ------- | ------------------- | ------ |
| svelte-5    | https://svelte.dev/docs      | 47    | 312    | indexed | 2026-09-23 10:00:00 | 1d     |
| tailwind-v4 | https://tailwindcss.com/docs | 89    | 654    | indexed | 2026-09-01 09:00:00 | 23d ⚠️ |

⚠️ **1 library has not been crawled in 14+ days.** Tell the user which
libraries are stale and offer to refresh them (manage_library action=refresh).

The Age column marks stale libraries with ⚠️, and the footer tells the assistant to surface that to the user. Use manage_library action=stale for a dedicated staleness report.

get_doc_page

Deep read. Retrieve full markdown content of a specific documentation page.

manage_library

Manage an existing documentation library or add a new one.

Use action=add to create a new library, action=rename to retitle an existing one, action=refresh to re-crawl, action=remove to delete a library, action=info to inspect its pages and stats, and action=stale to find outdated libraries.

Staleness workflow for assistants: run action=stale (or read the ⚠️ marks from list_libraries), tell the user which libraries are stale and how old they are, ask whether to refresh them — and only call action=refresh (one call per library) after the user agrees. Humans get the same flow in the CLI via docshark stale and the auto-prompt on docshark list.