ragora✓ ناجح

محتوى SKILL.md

---
name: ragora
description: Use Ragora MCP tools and REST API to discover, search, and synthesize answers from knowledge bases. Trigger when the user asks for grounded answers from Ragora collections, cross-collection comparison, source-backed summaries, due diligence research, or verification using marketplace data.
metadata: {"openclaw": {"emoji": "🔎", "homepage": "https://github.com/velarynai/ragora-openclaw", "requires": {"env": ["RAGORA_API_KEY"]}, "primaryEnv": "RAGORA_API_KEY"}}
---

# Ragora Skill for OpenClaw

Use this skill to answer questions with Ragora data. You have two integration paths:

1. **MCP (Model Context Protocol)** — preferred when your client supports MCP tool binding.
2. **REST API** — use directly via HTTP when MCP is unavailable or when you need fine-grained control.

Both paths share the same authentication, data model, and search capabilities.

## Source of Truth Docs

Consult these docs first when behavior differs across environments:

- MCP guide: `https://ragora.app/docs?section=mcp-guide`
- Getting started: `https://ragora.app/docs?section=getting-started`
- API overview: `https://ragora.app/docs?section=api-overview`
- Retrieve API: `https://ragora.app/docs?section=api-retrieve`
- Errors and limits: `https://ragora.app/docs?section=api-errors`
- Billing API: `https://ragora.app/docs?section=api-billing`

---

## Core Concepts

Before using any tools, understand the Ragora data model.

### Collections

A **collection** is a knowledge base — a curated set of documents indexed for semantic search. Each collection has:

- **Name** — human-readable label (e.g., "Employee Handbook").
- **Slug** — URL-safe identifier used in dynamic tools and API paths (e.g., `employee_handbook`).
- **Description** — what the collection contains and when to use it.
- **Stats** — document count, chunk count, last updated timestamp.

### Documents & Chunks

Each collection contains **documents** (files, pages, articles). Documents are split into **chunks** — small passages optimized for semantic retrieval. When you search, results are returned at the chunk level with metadata pointing back to the source document.

### Versions

Some collections support **versioned documentation** (e.g., API docs v1.0, v2.0). Use `list_versions_{slug}()` or the API to discover available versions, then pass a `version` parameter to scope your search.

### Tags & Filters

Collections may support:

- **Custom tags** — string labels attached to documents (e.g., `["legal", "msa", "2024"]`). Pass as `custom_tags` to narrow results.
- **Filters** — key-value metadata filters (e.g., `{"region": "US", "department": "engineering"}`). Pass as `filters` to constrain results.

### Credits & Billing

- **Own collections and subscriptions** — free MCP/API access, no credit cost.
- **Marketplace products (pay-per-use)** — each retrieval deducts credits based on seller pricing.
- Credits are measured in USD. Check with `check_balance()` or `GET /v1/billing/balance`.
- Top up at `https://app.ragora.app/settings/billing`.

---

## Connection Setup

### Authentication

All requests (MCP and REST) require a Ragora API key.

- **Format**: `sk_live_<uuid>` (e.g., `sk_live_a1b2c3d4-e5f6-7890-abcd-ef1234567890`)
- **Create one**: `https://app.ragora.app/settings/api-keys`
- **Shown once** — copy and store it securely at creation time.
- **Hashed on server** — SHA-256 + bcrypt. Ragora cannot recover a lost key; generate a new one.

### Security rules

- Never pass API keys in URL query parameters.
- Never print full API keys in logs, outputs, or final answers.
- If the key is missing or invalid, stop and ask the user for a valid key.
- Mask keys in any debug output: `sk_live_****...`.

### MCP endpoint

- **URL**: `https://mcp.ragora.app/mcp`
- **Auth header**: `Authorization: Bearer <RAGORA_API_KEY>`

OpenClaw config (YAML):

```yaml
name: ragora
type: http
url: https://mcp.ragora.app/mcp
headers:
  Authorization: Bearer ${RAGORA_API_KEY}
```

Claude Desktop / Cursor / VS Code config (JSON):

```json
{
  "mcpServers": {
    "ragora": {
      "type": "http",
      "url": "https://mcp.ragora.app/mcp",
      "headers": {
        "Authorization": "Bearer ${RAGORA_API_KEY}"
      }
    }
  }
}
```

> **Security note**: Set `RAGORA_API_KEY` as an environment variable in your OS or secret manager. Never hardcode the raw `sk_live_*` value in config files that may be committed to version control.

### REST API base URL

- **Base**: `https://api.ragora.app/v1`
- **Auth header**: `Authorization: Bearer <RAGORA_API_KEY>`
- **Content-Type**: `application/json` for all POST/PUT requests.

---

## Connectivity Check (Run First)

### Via MCP

1. Confirm server health:

```bash
curl -s https://mcp.ragora.app/health
```

2. Call `discover_collections()`. If it returns collections, you're connected.

3. If empty — user may need to access a knowledge base: `https://ragora.app/marketplace`

4. If credits are low — call `check_balance()` and tell user to top up at `https://app.ragora.app/settings/billing`.

### Via REST API

1. Confirm server health:

```bash
curl -s https://api.ragora.app/v1/health
```

2. List collections:

```bash
curl https://api.ragora.app/v1/collections \
  -H "Authorization: Bearer <RAGORA_API_KEY>"
```

3. If the response is `401` or `403`, the API key is invalid or expired. Ask the user to generate a new one.

---

## Operating Rules

- Start with `discover_collections()` (MCP) or `GET /v1/collections` (API) before targeted retrieval, unless the user explicitly names a known collection.
- Prefer targeted collection search over global search once you know the likely collections.
- Use global search for broad exploration only — ambiguity, unknown source, or discovery pass.
- Keep retrieval iterative: run multiple focused queries instead of one long query.
- Include source attribution from returned results in final answers.
- Call out uncertainty when evidence is partial, conflicting, or missing.
- If credits are low or errors mention billing limits, check balance and report constraints.
- Choose MCP tools when available; fall back to REST API when MCP binding fails or when you need features not exposed via MCP (e.g., pagination, collection metadata).

---

## MCP Tools Reference

### Static tools (always available)

| Tool | Parameters | Description |
|------|-----------|-------------|
| `discover_collections()` | none | List all accessible knowledge bases with descriptions, stats, available operations, and usage examples. |
| `search(query, top_k?)` | `query` (required), `top_k` (1-20, default 5) | Search across ALL accessible collections at once. |
| `search_collection(collection_name, query, top_k?, custom_tags?, filters?)` | `collection_name` (required), `query` (required), `top_k` (1-20, default 5), `custom_tags` (list of strings), `filters` (object) | Search a specific collection by name or slug. |
| `check_balance()` | none | Credits remaining and estimated USD value. |

### Dynamic tools (per-collection, returned in manifest)

The Gateway generates these tools for each collection you have access to. The `{slug}` is the collection's URL-safe name (e.g., `employee_handbook`, `k8s_troubleshooting`).

| Tool | Parameters | Description |
|------|-----------|-------------|
| `search_{slug}(query, top_k?, version?, custom_tags?, filters?)` | `query` (required), `top_k` (1-20, default 5), `version` (optional string), `custom_tags` (list of strings), `filters` (object) | Semantic search within the collection. |
| `get_topic_{slug}(topic)` | `topic` (required string) | Retrieve information about a specific topic from the collection. |
| `list_versions_{slug}()` | none | List all available documentation versions for the collection. |

### MCP Resources

| URI | Description |
|-----|-------------|
| `ragora://collections` | Lists all accessible collections with metadata, stats, and available operations. |

### MCP Prompts

| Prompt | Parameters | Description |
|--------|-----------|-------------|
| `search_collection_prompt` | `collection_name`, `query` | Pre-built prompt for searching a specific collection. |
| `summarize_collection` | `collection_name` | Pre-built prompt for summarizing an entire collection. |
| `compare_sources` | `collection_names`, `question` | Pre-built prompt for comparing information across multiple collections. |

---

## REST API Reference

Use these endpoints when MCP tool binding is unavailable, or when you need direct HTTP control.

**All endpoints require**: `Authorization: Bearer <RAGORA_API_KEY>`

### Health check

```
GET https://api.ragora.app/v1/health
```

Response: `200 OK` with `{"status": "ok"}` if the service is up.

### List collections

```
GET https://api.ragora.app/v1/collections
```

Returns all collections accessible to the authenticated user.

Response:

```json
{
  "collections": [
    {
      "name": "Employee Handbook",
      "slug": "employee_handbook",
      "description": "Company policies, benefits, and procedures",
      "stats": {
        "document_count": 45,
        "chunk_count": 1230,
        "last_updated": "2025-11-15T08:30:00Z"
      },
      "supported_features": ["search", "get_topic", "versions", "filters"]
    }
  ]
}
```

### Search across all collections

```
POST https://api.ragora.app/v1/search
```

Request:

```json
{
  "query": "vacation policy for remote employees",
  "top_k": 5
}
```

Response:

```json
{
  "results": [
    {
      "content": "Remote employees are entitled to 20 days of paid vacation per year...",
      "score": 0.94,
      "source": {
        "collection": "employee_handbook",
        "document": "benefits-guide.md",
        "chunk_id": "ch_abc123"
      },
      "metadata": {}
    }
  ],
  "usage": {
    "cost_usd": 0.0,
    "balance_remaining_usd": 99.95
  }
}
```

### Search a specific collection

```
POST https://api.ragora.app/v1/collections/{slug}/search
```

Request:

```json
{
  "query": "log retention duration and deletion policy",
  "top_k": 5,
  "version": "2.0",
  "custom_tags": ["compliance", "soc2"],
  "filters": {
    "region": "US"
  }
}
```

Response: same structure as global search, but scoped to the named collection.

### Get topic from a collection

```
POST https://api.ragora.app/v1/collections/{slug}/topic
```

Request:

```json
{
  "topic": "remote work policy"
}
```

Response:

```json
{
  "content": "Detailed information about the remote work policy...",
  "source": {
    "collection": "employee_handbook",
    "document": "remote-work.md"
  },
  "usage": {
    "cost_usd": 0.0,
    "balance_remaining_usd": 99.95
  }
}
```

### List versions for a collection

```
GET https://api.ragora.app/v1/collections/{slug}/versions
```

Response:

```json
{
  "versions": [
    {"version": "2.0", "label": "v2.0 (latest)", "is_default": true},
    {"version": "1.5", "label": "v1.5", "is_default": false},
    {"version": "1.0", "label": "v1.0 (legacy)", "is_default": false}
  ]
}
```

### Check balance

```
GET https://api.ragora.app/v1/billing/balance
```

Response:

```json
{
  "credits_remaining": 9950,
  "estimated_usd": 99.50,
  "currency": "USD"
}
```

### MCP Gateway endpoints (tool proxy)

If you need to call MCP tools via REST (e.g., dynamic tools like `search_employee_handbook`):

**Get manifest** — lists all available MCP tools for your account:

```
GET https://api.ragora.app/v1/mcp/manifest
```

**Execute a tool** — call any MCP tool by name:

```
POST https://api.ragora.app/v1/mcp/execute
```

Request:

```json
{
  "tool": "search_employee_handbook",
  "arguments": {
    "query": "vacation policy",
    "top_k": 5
  }
}
```

Response:

```json
{
  "content": [
    {
      "type": "text",
      "text": "Found 5 results:\n\n1. **Vacation Policy** (score: 0.95)\n   Remote employees are entitled to...\n   Source: benefits-guide.md"
    }
  ],
  "usage": {
    "cost_usd": 0.0,
    "balance_remaining_usd": 99.95
  }
}
```

---

## Error Codes & Status Handling

### HTTP status codes

| Status | Meaning | Agent action |
|--------|---------|--------------|
| `200` | Success | Process results normally. |
| `400` | Bad request — malformed query, missing required param | Check request format. Fix the query and retry. |
| `401` | Unauthorized — missing or invalid API key | Stop. Ask the user to provide a valid `sk_live_` key. |
| `403` | Forbidden — key is valid but lacks access to this collection | Inform user they need to purchase/subscribe to this collection at the marketplace. |
| `404` | Not found — collection slug or endpoint doesn't exist | Check the slug with `discover_collections()` or `GET /v1/collections`. |
| `422` | Validation error — params are present but invalid (e.g., `top_k=50`) | Read the error message, fix the parameter, and retry. |
| `429` | Rate limited — too many requests | Wait and retry with exponential backoff (see Rate Limiting below). |
| `402` | Payment required — insufficient credits | Call `check_balance()`. Tell user to top up at billing page. |
| `500` | Server error | Retry once after 2 seconds. If it persists, inform user of a temporary service issue. |
| `503` | Service unavailable | Retry once after 5 seconds. If it persists, inform user. |

### Error response format

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Your balance is too low to complete this search. Current balance: $0.05.",
    "details": {}
  }
}
```

### Common error codes in response body

| Code | Description | Agent action |
|------|-------------|--------------|
| `invalid_api_key` | Key format wrong or key revoked | Ask user for a new key. |
| `expired_api_key` | Key has expired | Ask user to generate a new key at dashboard. |
| `insufficient_credits` | Not enough credits for this retrieval | Report balance and link to billing. |
| `collection_not_found` | Slug doesn't match any collection | Re-run discovery, check spelling. |
| `collection_access_denied` | User hasn't purchased access | Link user to the marketplace. |
| `rate_limit_exceeded` | Too many requests in window | Back off and retry. |
| `invalid_query` | Query is empty or too long | Fix and retry with a shorter, clearer query. |
| `version_not_found` | Requested version doesn't exist | Call `list_versions_{slug}()` to see valid versions. |

---

## Rate Limiting & Retry Strategy

### Limits

- **MCP tools**: 60 calls per minute per API key.
- **REST API**: 120 requests per minute per API key.
- Rate limit headers are returned on every response:
  - `X-RateLimit-Limit` — max requests in the window.
  - `X-RateLimit-Remaining` — requests left in the current window.
  - `X-RateLimit-Reset` — Unix timestamp when the window resets.

### Retry strategy

When you receive a `429` response:

1. Read the `Retry-After` header (seconds to wait) if present.
2. If no `Retry-After`, use exponential backoff: wait 1s, then 2s, then 4s.
3. Maximum 3 retries before giving up and informing the user.
4. Never retry `401` or `403` — these require user action, not waiting.

### Best practices to avoid rate limits

- Batch your queries logically: 3-5 focused queries per task, not 20 rapid-fire calls.
- Use `top_k=10-15` instead of making multiple `top_k=3` calls for the same question.
- Cache `discover_collections()` results within a session — collection lists rarely change mid-conversation.

---

## Authentication Troubleshooting

| Symptom | Likely cause | Fix |
|---------|-------------|-----|
| `401 Unauthorized` on every call | Missing or malformed `Authorization` header | Ensure header is exactly `Authorization: Bearer sk_live_xxxxx`. No extra spaces, no quotes around the token. |
| `401` but key looks correct | Key was revoked or regenerated | Ask user to check active keys at `https://app.ragora.app/settings/api-keys`. |
| `401` with `invalid_api_key` code | Key format is wrong (e.g., missing `sk_live_` prefix) | Verify format: must start with `sk_live_` followed by a UUID. |
| `401` with `expired_api_key` code | Key has an expiration and it passed | Generate a new key from the dashboard. |
| `403 Forbidden` | Key is valid but doesn't have access to the requested collection | User needs to purchase or subscribe to the collection. |
| MCP tools not appearing | MCP server not configured or wrong URL | Verify MCP URL is `https://mcp.ragora.app/mcp` and header is set. Run health check. |
| MCP tools appear but return errors | Key in MCP config is a placeholder | Replace `sk_live_xxx` with the actual key. |
| `ECONNREFUSED` or timeout | Network issue or service outage | Check `https://mcp.ragora.app/health`. If down, fall back to REST API or wait. |

---

## Core Workflow

### 1. Understand intent

- Classify request type: factual lookup, summary, comparison, extraction, or verification.
- Identify likely domains/collections from user wording.

### 2. Discover scope

- Run `discover_collections()` (MCP) or `GET /v1/collections` (API).
- Select 1-3 collections most relevant to the question.
- If no relevant collection exists, state that explicitly and stop.

### 3. Retrieve evidence

- **First pass**: one targeted query per selected collection.
- **Second pass**: refine with specific sub-queries (dates, entities, claims, thresholds).
- Tune `top_k` based on task:
  - `top_k=3-5` for direct factual questions.
  - `top_k=8-12` for comparisons or comprehensive summaries.
  - `top_k=15-20` for exhaustive research or due diligence.

### 4. Synthesize

- Merge evidence by claim, not by source order.
- Resolve conflicts by preferring direct passages and recency cues in content.
- Distinguish facts from inferences.

### 5. Respond

- Give a concise answer first.
- Then provide evidence bullets with collection/source references.
- End with gaps, caveats, or suggested follow-up queries when confidence is not high.

---

## Multi-Step Workflow Examples

### Research a topic across multiple collections

**Scenario**: User asks "What is our data retention policy and how does it compare to SOC 2 requirements?"

1. `discover_collections()` → find `security_handbook`, `compliance_docs`, `soc2_guide`
2. `search_collection("security_handbook", "data retention policy duration", top_k=5)`
3. `search_collection("compliance_docs", "SOC 2 data retention requirements", top_k=5)`
4. `search_collection("soc2_guide", "retention controls audit evidence", top_k=5)`
5. Synthesize: compare internal policy against SOC 2 requirements, note gaps.
6. Respond with findings, citing each collection.

### Compare two vendor contracts

**Scenario**: User asks "Compare the SLA terms between Vendor A and Vendor B."

1. `discover_collections()` → find `vendor_a_contract`, `vendor_b_contract`
2. `search_collection("vendor_a_contract", "SLA uptime guarantees penalties", top_k=8)`
3. `search_collection("vendor_b_contract", "SLA uptime guarantees penalties", top_k=8)`
4. Second pass for specifics:
   - `search_collection("vendor_a_contract", "termination notice period remedies", top_k=5)`
   - `search_collection("vendor_b_contract", "termination notice period remedies", top_k=5)`
5. Build comparison table: uptime %, penalty structure, notice periods, exclusions.
6. Highlight key differences and risks.

### Due diligence deep dive

**Scenario**: User asks "Summarize everything we know about Company X's security posture."

1. `search("Company X security audit penetration test vulnerability", top_k=15)` — broad discovery pass.
2. Identify which collections returned results (e.g., `due_diligence_reports`, `vendor_assessments`).
3. Targeted follow-up:
   - `search_collection("due_diligence_reports", "Company X SOC 2 ISO 27001 certifications", top_k=10)`
   - `search_collection("vendor_assessments", "Company X data encryption access controls", top_k=10)`
   - `search_collection("due_diligence_reports", "Company X incident history breach", top_k=5)`
4. Organize findings by category: certifications, technical controls, incident history, gaps.
5. Present with confidence levels and note areas with no data.

### Versioned documentation lookup

**Scenario**: User asks "What changed in the authentication flow between API v1 and v2?"

1. `list_versions_api_docs()` → returns `["1.0", "2.0"]`
2. `search_api_docs(query="authentication flow token exchange", version="1.0", top_k=5)`
3. `search_api_docs(query="authentication flow token exchange", version="2.0", top_k=5)`
4. Diff the results: what was added, changed, or removed.
5. Present a clear changelog-style summary.

### REST API workflow (no MCP)

**Scenario**: MCP binding is unavailable. User asks "Find our vacation policy."

1. Health check:
```bash
curl -s https://api.ragora.app/v1/health
```

2. List collections:
```bash
curl https://api.ragora.app/v1/collections \
  -H "Authorization: Bearer $RAGORA_API_KEY"
```

3. Search the relevant collection:
```bash
curl -X POST https://api.ragora.app/v1/collections/employee_handbook/search \
  -H "Authorization: Bearer $RAGORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "vacation policy paid time off", "top_k": 5}'
```

4. Parse the `results` array, extract `content` and `source` fields, and compose the answer.

---

## Query Patterns

Use short, specific queries. Prefer multiple passes over one monolithic query.

### By task type

| Task | Query pattern | Example |
|------|--------------|---------|
| Factual lookup | `"<entity> <metric/attribute> <time period>"` | `"ACME Corp revenue 2024 Q3"` |
| Policy/requirements | `"<policy type> eligibility criteria exceptions"` | `"parental leave eligibility criteria exceptions"` |
| Comparison | Run same query across each collection | `"pricing limits SLA exclusions"` × 2 collections |
| Validation | First `"<claim>"`, then `"counterexample exception to <claim>"` | `"all employees get 20 vacation days"` then `"exceptions to vacation day policy"` |
| Extraction | `"<entity> <specific data point>"` | `"ACME Corp CEO contact information"` |
| Timeline | `"<entity> <event type> chronological"` | `"product launches timeline 2023 2024"` |

### Query refinement strategy

1. **Start broad**: `"data retention policy"` — see what's available.
2. **Narrow by entity**: `"customer data retention policy"` — scope to a specific domain.
3. **Narrow by attribute**: `"customer data retention duration deletion schedule"` — get specifics.
4. **Add constraints**: Use `filters` and `custom_tags` if results are noisy.

---

## Tooling Playbook

### Discover collections

MCP:
```text
discover_collections()
```

API:
```bash
curl https://api.ragora.app/v1/collections \
  -H "Authorization: Bearer $RAGORA_API_KEY"
```

### Broad search when unsure

MCP:
```text
search(query="SOC 2 retention policy for customer logs", top_k=8)
```

API:
```bash
curl -X POST https://api.ragora.app/v1/search \
  -H "Authorization: Bearer $RAGORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SOC 2 retention policy for customer logs", "top_k": 8}'
```

### Targeted collection search

MCP:
```text
search_collection(
  collection_name="security-handbook",
  query="log retention duration and deletion policy",
  top_k=5
)
```

API:
```bash
curl -X POST https://api.ragora.app/v1/collections/security_handbook/search \
  -H "Authorization: Bearer $RAGORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "log retention duration and deletion policy", "top_k": 5}'
```

### Search with version

MCP:
```text
search_api_docs(
  query="authentication flow changes",
  version="2.0",
  top_k=5
)
```

API:
```bash
curl -X POST https://api.ragora.app/v1/collections/api_docs/search \
  -H "Authorization: Bearer $RAGORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication flow changes", "version": "2.0", "top_k": 5}'
```

### Get topic from a collection

MCP:
```text
get_topic_employee_handbook(topic="remote work policy")
```

API:
```bash
curl -X POST https://api.ragora.app/v1/collections/employee_handbook/topic \
  -H "Authorization: Bearer $RAGORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic": "remote work policy"}'
```

### Filtered search

MCP:
```text
search_collection(
  collection_name="contracts",
  query="termination for convenience notice period",
  top_k=10,
  custom_tags=["msa", "legal"],
  filters={"region": "US"}
)
```

API:
```bash
curl -X POST https://api.ragora.app/v1/collections/contracts/search \
  -H "Authorization: Bearer $RAGORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "termination for convenience notice period", "top_k": 10, "custom_tags": ["msa", "legal"], "filters": {"region": "US"}}'
```

### Credit check

MCP:
```text
check_balance()
```

API:
```bash
curl https://api.ragora.app/v1/billing/balance \
  -H "Authorization: Bearer $RAGORA_API_KEY"
```

### Compare across collections

MCP prompt:
```text
compare_sources(
  collection_names=["vendor-a-docs", "vendor-b-docs"],
  question="What are the SLA differences?"
)
```

API (manual — run two searches and compare):
```bash
# Search vendor A
curl -X POST https://api.ragora.app/v1/collections/vendor_a_docs/search \
  -H "Authorization: Bearer $RAGORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SLA uptime guarantees penalties", "top_k": 8}'

# Search vendor B
curl -X POST https://api.ragora.app/v1/collections/vendor_b_docs/search \
  -H "Authorization: Bearer $RAGORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SLA uptime guarantees penalties", "top_k": 8}'
```

---

## Context Management

### Choosing `top_k`

| Scenario | Recommended `top_k` | Rationale |
|----------|---------------------|-----------|
| Simple factual question | 3-5 | Few precise results keep context small. |
| Multi-facet question | 5-8 | Need coverage across sub-topics. |
| Comparison across collections | 8-12 per collection | Need enough evidence from each side. |
| Exhaustive research / due diligence | 15-20 | Comprehensive coverage at the cost of more context. |
| Quick validation of a claim | 2-3 | Just need to confirm or deny. |

### Managing context window size

- **Prefer targeted searches over global searches.** `search_collection()` returns fewer, more relevant results than `search()`.
- **Summarize as you go.** After retrieving results, extract the key facts before moving to the next query. Don't accumulate raw results.
- **Use multi-pass retrieval.** First pass: broad query with `top_k=5`. Read results. Second pass: specific follow-up queries targeting gaps.
- **Drop low-relevance results.** If a result has a low relevance score or doesn't relate to the question, ignore it.
- **Don't retrieve what you already know.** If a previous query already answered part of the question, don't re-query for it.

### When results are too large

If a single query returns more text than is useful:

1. Reduce `top_k` to 3.
2. Add `custom_tags` or `filters` to narrow scope.
3. Use a more specific query instead of a broad one.
4. Focus on the highest-scoring results and discard the rest.

### When results are insufficient

If a query returns no results or irrelevant results:

1. Broaden the query: remove specific terms, use synonyms.
2. Try global `search()` instead of collection-specific.
3. Check if the collection exists with `discover_collections()`.
4. Try a different collection if multiple are available.
5. If still empty, tell the user that no relevant data was found.

---

## Output Formatting Guidelines

### Standard response structure

```
**Answer**: <2-6 sentence direct answer>

**Evidence**:
- <claim> — *<collection_name> / <source_document>*
- <claim> — *<collection_name> / <source_document>*
- <claim> — *<collection_name> / <source_document>*

**Caveats**:
- <what is missing, uncertain, or conflicting>

**Suggested follow-ups** (if applicable):
- <exact query the user could ask next>
```

### Source citation rules

- Always cite the **collection name** and **source document** for every claim.
- Format: `— *Collection Name / document-name.md*`
- If multiple results support the same claim, cite the highest-scoring one.
- If results conflict, cite both and note the conflict.

### Confidence indicators

- **High confidence**: multiple results agree, high relevance scores (>0.85), from authoritative collections.
- **Medium confidence**: single result or moderate scores (0.6-0.85). Note: "Based on a single source."
- **Low confidence**: low scores (<0.6), tangential results, or inferred conclusions. Note: "This is inferred and may need verification."

### Comparison format

When comparing across collections, use a table:

```
| Aspect | Vendor A | Vendor B |
|--------|----------|----------|
| Uptime SLA | 99.9% | 99.95% |
| Penalty | 5% credit per hour | 10% credit per hour |
| Notice period | 30 days | 60 days |

*Sources: vendor_a_contract/sla.md, vendor_b_contract/sla.md*
```

---

## Failure Handling

| Failure | Agent action |
|---------|-------------|
| **No results** | Broaden wording, remove overly specific constraints, retry with `search()`. If still empty, inform user. |
| **Too many noisy results** | Constrain by collection, add `custom_tags`/`filters`, use narrower entity/date terms. |
| **Conflicting evidence** | Present both sides, note the conflict, cite both sources, and propose a follow-up query to resolve. |
| **Access denied (403)** | Explain that collection access may need to be purchased. Link to marketplace. |
| **Credit errors (402)** | Run `check_balance()`, report the balance, and link to billing page. |
| **Rate limited (429)** | Wait per `Retry-After` header or use exponential backoff. Max 3 retries. |
| **Server error (500/503)** | Retry once after 2-5 seconds. If it persists, inform user of a temporary issue. |
| **MCP connection failure** | Fall back to REST API endpoints. Inform user of the switch. |
| **Timeout** | Reduce `top_k`, simplify the query, and retry. |
| **Invalid collection slug** | Re-run `discover_collections()` and check available slugs. |

---

## Quality Bar

- Never fabricate unseen facts — all claims must come from retrieved evidence.
- Always ground claims in retrieved evidence with source citations.
- Prefer precise wording over broad generalization.
- Keep final responses concise, decision-oriented, and source-backed.
- Distinguish between directly stated facts and inferred conclusions.
- When evidence is incomplete, explicitly state what is missing rather than guessing.
- If a question cannot be answered from available collections, say so directly.

الترخيص

الترخيص المُعلن: MIT

MIT License

Copyright (c) 2026 openclaw

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

عرض الترخيص في المستودع المصدري — النسخة المنشورة هناك هي المرجع.