Skip to main content
SkillDiscs exposes REST endpoints that map cleanly onto LLM tool definitions. This guide shows the minimal tool surface for retrieval-augmented agents. Three tools cover ~95% of agent use cases:
  1. search_knowledge → POST /api/v1/search
  2. read_disk → GET /api/v1/disks/{id}
  3. list_disks → GET /api/v1/disks?scope=…&category=…&tag=… (browsing)
Skip batch unless you measure round-trip latency as a bottleneck.

​
Anthropic / Claude tool definition

{
  "name": "search_knowledge",
  "description": "Search the user's personal knowledge base (their imported articles, videos, PDFs) by natural-language query. Returns the most relevant section excerpts.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Natural-language search query" },
      "limit": { "type": "integer", "default": 5, "maximum": 25 }
    },
    "required": ["query"]
  }
}
In your tool handler, forward to: 
const r = await fetch('https://skilldiscs.com/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SKILLDISCS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(input),
})
return await r.json()
When building context for the model, use section_text when present and fall back to snippet: 
const { results } = await r.json()
const context = results.map(hit => ({
  title: hit.disk_title,
  text: hit.section_text ?? hit.snippet,
  key_points: hit.key_points ?? [],
  redacted: hit.redacted,
}))

​
OpenAI / GPT function calling

Same JSON Schema, register under tools with type: "function". Forward to the same endpoint.

​
Prompt template

You have access to the user's personal knowledge base via three tools:
- search_knowledge(query, limit) — semantic search across owned Disks
- read_disk(id) — metadata, key points, and conditional text for one Disk
- list_disks(scope?, category?, tag?) — browse the library

Always cite the Disk title when referencing retrieved content.
Prefer search_knowledge over read_disk unless the user names a specific Disk.
If a result is redacted, treat snippet/key_points as context and do not imply access to the full source.

​
Gotchas

  • Never embed the API key in a client-side bundle. Always proxy through your backend.
  • Search is per-user and owned-Disk scoped in current production.
  • Check redacted. Full source text is only returned for owner-private Disks.
  • Embeddings are computed at import time; newly imported Disks are searchable within seconds.