uriburner-opal-agent-skills

name	uriburner-opal-agent-skills
description	Comprehensive toolkit for URIBurner MCP Server enabling semantic data discovery, Knowledge Graph exploration, SPARQL/SQL query execution, RDF sponging, and database management. Use native MCP tools for queries; ChatPromptComplete only when user explicitly requests Gemini-powered analysis.

URIBurner OPAL Agent Skills

Overview

This skill provides comprehensive guidance for using URIBurner MCP Server's suite of tools for semantic data operations, Knowledge Graph exploration, and database management. URIBurner offers powerful native tools that should be used directly for queries and data operations.

Key Principle: Use URIBurner's native MCP tools (execute_spasql_query, sparqlQuery, etc.) for all standard operations. Only invoke ChatPromptComplete when the user explicitly requests Gemini-powered AI analysis or when using SPARQL Agent 121's advanced features.

→ For execution modalities and environment-specific routing: Read references/protocol-routing.md

⛔ PRE-BUILD CHECK: Before producing output, re-read the relevant workflow section above and re-read any checklists or verification gates defined in this skill. Confirm each checklist item before writing output. Build to pass — do not retro-fit. Apply the CLAUDE.md Anti-Drift Protocol: re-read spec section before build, gate-first validation, section-by-section delivery.

Execution Routing

Default execution order:

1. URIBurner REST functions (unauthenticated or with existing session)
2. Terminal-owned OAuth flow — when the endpoint requires OAuth 2.0 authentication, execute the OAuth flow from the terminal (authorization code, client credentials, or device flow), capture the Bearer token, and inject it into subsequent REST/OpenAPI calls via Authorization: Bearer {token} headers
3. MCP via https://linkeddata.uriburner.com/chat/mcp/messages or https://linkeddata.uriburner.com/chat/mcp/sse
4. OPAL Agent routing using canonical OPAL-recognizable function names
5. Authenticated LLM-mediated execution via https://linkeddata.uriburner.com/chat/functions/chatPromptComplete
6. Direct curl as last resort

If the user explicitly names a protocol, honor that preference instead of the default order.

Prerequisites

• Access to URIBurner MCP Server
• Understanding of SPARQL basics (recommended)
• Familiarity with semantic web concepts (helpful)
• Knowledge of SPARQL Agent 121 workflow (for advanced usage)

Core URIBurner MCP Tools

URIBurner MCP Server provides these native tools, listed by frequency of use:

Primary Query Tools

1. execute_spasql_query

Purpose: Execute SPARQL-within-SQL queries against local Knowledge Graph
When to use: Primary tool for KG queries on local URIBurner instance
Parameters:

• sql (required) - SPASQL query text (prefix with "SPARQL" keyword)
• format (optional) - Response format: "json", "jsonl", "markdown" (default: "json")
• max_rows (optional) - Maximum rows to return (default: varies)
• timeout (optional) - Query timeout in seconds (default: 30)

Example:

{
  "sql": "SPARQL SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10",
  "format": "json",
  "max_rows": 10
}

With Inference Enabled:

{
  "sql": "SPARQL DEFINE input:inference 'urn:rdfs:subclass:subproperty:inference:rules' SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10",
  "format": "json"
}

2. sparqlQuery

Purpose: Execute SPARQL queries against local endpoint
When to use: Standard SPARQL queries on URIBurner's default endpoint
Parameters:

• query (required) - SPARQL query text
• format (optional) - Response format: "json", "jsonl", "markdown"
• timeout (optional) - Query timeout in seconds

Example:

{
  "query": "SELECT ?type (COUNT(?entity) AS ?count) WHERE { ?entity a ?type } GROUP BY ?type ORDER BY DESC(?count) LIMIT 10",
  "format": "json"
}

3. sparqlRemoteQuery

Purpose: Execute SPARQL queries against remote endpoints
When to use: Querying external SPARQL endpoints (DBpedia, Wikidata, etc.)
Parameters:

• url (required) - Remote SPARQL endpoint URL
• query (required) - SPARQL query text
• format (optional) - Response format
• timeout (optional) - Query timeout in seconds
• apiKey (optional) - API key for authenticated endpoints

Example:

{
  "url": "https://dbpedia.org/sparql",
  "query": "SELECT * WHERE { ?s a dbo:Person } LIMIT 5",
  "format": "json"
}

4. execute_sql_query

Purpose: Execute SQL queries against local databases
When to use: Querying relational databases (Northwind demo, etc.)
Parameters:

• sql (required) - SQL query text (do NOT terminate with semicolon)
• format (optional) - Response format
• max_rows (optional) - Result limit
• timeout (optional) - Query timeout

Example:

{
  "sql": "SELECT * FROM Demo.demo.Customers LIMIT 10",
  "format": "json"
}

Data Retrieval Tools

5. WEB_FETCH

Purpose: Fetch web content like a browser
When to use: Retrieving web pages for analysis or RDF extraction
Parameters:

• url (required) - URL to fetch
• headers (optional) - HTTP headers
• timeout_seconds (optional) - Request timeout
• max_redirects (optional) - Maximum redirects to follow

Example:

{
  "url": "https://www.w3.org/",
  "timeout_seconds": 30
}

6. SPONGE_URL

Purpose: Perform RDF extraction (sponging) on a URL
When to use: Converting web content to RDF triples
Parameters:

• url (required) - URL to sponge
• format (optional) - Response format
• max_rows (optional) - Result limit
• timeout (optional) - Query timeout

Example:

{
  "url": "https://example.com/data",
  "format": "json"
}

Schema Discovery Tools

7. sparql_list_entity_types

Purpose: Retrieve all entity types in an RDF graph
When to use: Discovering what kinds of entities exist in the Knowledge Graph
Parameters:

• graph_iri (required) - Target graph IRI
• format (optional) - Response format

Example:

{
  "graph_iri": "urn:default:graph",
  "format": "markdown"
}

8. sparql_list_entity_types_samples

Purpose: Retrieve entity types with sample entities and counts
When to use: Getting an overview of entity distribution
Parameters:

• graph_iri (required) - Target graph IRI
• format (optional) - Response format

Example:

{
  "graph_iri": "urn:default:graph",
  "format": "markdown"
}

Tool Selection Guide

Use this decision tree to select the appropriate tool:

Query Type?
├─ Knowledge Graph Query
│  ├─ Local URIBurner data?
│  │  ├─ Need entity type discovery? → sparql_list_entity_types
│  │  ├─ Standard query? → execute_spasql_query (PREFERRED)
│  │  └─ No results? → Retry with inference pragma
│  └─ Remote endpoint? → sparqlRemoteQuery
│
├─ SQL Database Query → execute_sql_query
│
├─ Web Content Retrieval
│  ├─ Just fetch content? → WEB_FETCH
│  └─ Extract RDF? → SPONGE_URL
│
└─ User Explicitly Requests Gemini/SPARQL Agent 121? → ChatPromptComplete

SPARQL Agent 121 KG-First Workflow

When using ChatPromptComplete with SPARQL Agent 121 (assistant_config_id: "new-sparql-agent-121"), the agent follows a structured Knowledge Graph-First workflow:

Workflow Overview

The agent prioritizes finding answers in Knowledge Graphs before synthesizing responses, following these steps:

Step 1: Basic Label Match

Goal: Find entities with labels matching the prompt

Query Template (Virtuoso):

SELECT DISTINCT ?entity ?value
WHERE {
  ?entity ?attribute ?value.
  ?value bif:contains "'{{entire-prompt-text}}'" option (score ?sc)
}
ORDER BY DESC(?sc)
LIMIT 10

Key Points:

• Uses full-text search via bif:contains() for Virtuoso
• Searches entire prompt text as-is
• Returns scored results by relevance

Step 2: Semantic Breakdown

Goal: If Step 1 yields no results, decompose the prompt

Actions:

1. Break prompt into subject, predicate, object components
2. Determine relevant entity types:
   • schema:Question / schema:FAQPage
   • schema:DefinedTermSet
   • skos:ConceptScheme
   • schema:HowTo
3. Identify target graphs to query

Entity Type Discovery Template:

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX schema: <http://schema.org/>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>

SELECT ?type (COUNT(?entity) AS ?count) (SAMPLE(?entity) AS ?sampleEntity)
WHERE {
  ?entity rdf:type ?type .
  FILTER (?type IN (
    schema:FAQPage,
    schema:Question,
    schema:DefinedTermSet,
    skos:ConceptScheme,
    schema:HowTo
  ))
}
GROUP BY ?type
ORDER BY DESC(?count)

Step 3: Explore & Identify

Goal: Try semantic variants of the prompt

Actions:

1. Generate up to 3 semantically similar prompt variants
2. Retry label match with each variant
3. Query configured remote endpoints in fallback order
4. Maximum queries per prompt: 6

Fallback Endpoints (in order):

1. https://linkeddata.uriburner.com/sparql (default)
2. https://kingsley.idehen.net/sparql
3. https://demo.openlinksw.com/sparql

Step 4: Query for IRIs and Text

Goal: Construct targeted query for answers with provenance

Query Pattern:

PREFIX schema: <http://schema.org/>

SELECT ?question ?answer ?questionIRI ?answerIRI
WHERE {
  ?questionIRI a schema:Question ;
               schema:name ?question ;
               schema:acceptedAnswer ?answerIRI .
  ?answerIRI schema:text ?answer .
  
  FILTER(bif:contains(?question, "'{{search_terms}}'"))
}
ORDER BY DESC(bif:score(?question))
LIMIT 10

Returns:

• Question and answer text
• Source IRIs for provenance
• Optional relevance scores

Step 5: Format with Encoded Hyperlinks

Goal: Present results with clickable provenance links

Link Generation Rules:

For local SPASQL queries (same origin as instance):

https://linkeddata.uriburner.com/describe/?uri={URL_ENCODED_IRI}

For remote SPARQL endpoints:

https://{endpoint_host}/describe/?uri={URL_ENCODED_IRI}

Example:

• Entity IRI: https://kingsley.idehen.net/DAV/home/file.pdf#Question_1
• Query source: https://kingsley.idehen.net/sparql
• Correct link: https://kingsley.idehen.net/describe/?uri=https%3A%2F%2Fkingsley.idehen.net%2FDAV%2Fhome%2Ffile.pdf%23Question_1

Markdown Format:

**Question:** [What is RDF?](https://linkeddata.uriburner.com/describe/?uri=...)

**Answer:** [RDF (Resource Description Framework) is...](https://linkeddata.uriburner.com/describe/?uri=...)

Fallback Strategy (When KG-First Fails)

If the initial KG-first workflow yields no results, the agent follows this escalation:

1. Retry with Inference/Reasoning

Action: Enable RDFS reasoning for ontology-level equivalence and subsumption

Virtuoso Pragma:

DEFINE input:inference 'urn:rdfs:subclass:subproperty:inference:rules'
SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10

When to use:

• Empty results from initial queries
• Domain with rich ontology hierarchies
• Need to infer subclass/subproperty relationships

2. Try Additional Remote Endpoints

Action: Query fallback endpoints in configured order

Process:

1. Execute same query against next endpoint
2. Keep entity IRIs scoped to originating endpoint
3. Sequential retry delay: 1 second between endpoints
4. Respect per-endpoint timeout: 30 seconds

3. Semantic Similarity Refinement

Action: Generate broader or narrower query variants

Strategies:

• Use broader terms (parent concepts)
• Use more specific terms (child concepts)
• Try synonyms and related terms
• Adjust filters to be less restrictive

Maximum retries: 2 semantic variants

4. Final Report to User

Action: If all attempts fail, provide audit block and options

Audit Block Contents:

{
  "queries_executed": [
    {
      "query_text": "SPARQL SELECT...",
      "endpoint_url": "https://linkeddata.uriburner.com/sparql",
      "start_timestamp": "2025-10-27T10:30:00Z",
      "end_timestamp": "2025-10-27T10:30:02Z",
      "status": "no_results",
      "result_count": 0
    }
  ],
  "endpoints_attempted": [
    "https://linkeddata.uriburner.com/sparql",
    "https://kingsley.idehen.net/sparql"
  ],
  "failure_reason": "No matching entities found in any endpoint",
  "total_time_seconds": 45
}

User Options:

1. Synthesize answer without KG backing
2. Try more endpoints
3. Provide semantic variants manually
4. Refine the question

Important: Finding a result on a remote endpoint does NOT change the default data source for subsequent prompts. Processing always returns to the top of the workflow loop.

SPARQL Query Syntax Rules

For Virtuoso Backend (Default)

Full-Text Search:

# ✅ PREFERRED - Use bif:contains()
SELECT ?entity ?value WHERE {
  ?entity ?attr ?value .
  ?value bif:contains "'search term'" option (score ?sc)
}
ORDER BY DESC(?sc)

# ❌ AVOID - REGEX is slower
SELECT ?entity ?value WHERE {
  ?entity ?attr ?value .
  FILTER(REGEX(?value, "search term", "i"))
}

Combining Multiple Terms:

# ✅ PREFERRED - Single bif:contains with logical operators
SELECT ?entity ?value WHERE {
  ?entity ?attr ?value .
  ?value bif:contains "'term1 AND term2 OR term3'" option (score ?sc)
}

# ❌ AVOID - Multiple separate filters
SELECT ?entity ?value WHERE {
  ?entity ?attr ?value .
  FILTER(bif:contains(?value, "'term1'"))
  FILTER(bif:contains(?value, "'term2'"))
}

Inference Pragma:

# Enable RDFS reasoning
DEFINE input:inference 'urn:rdfs:subclass:subproperty:inference:rules'
SELECT ?s ?p ?o WHERE { ?s ?p ?o }

For Non-Virtuoso Backends

Use Standard SPARQL:

SELECT ?entity ?value WHERE {
  ?entity ?attr ?value .
  FILTER(REGEX(?value, "search term", "i"))
}

# Combine with logical operators
FILTER(REGEX(?value, "term1", "i") && REGEX(?value, "term2", "i"))

ChatPromptComplete (SPARQL Agent 121)

When to Use ChatPromptComplete

✅ USE when user explicitly requests:

• "Use Gemini to analyze..."
• "Ask the SPARQL agent about..."
• "Use SPARQL Agent 121 to..."
• "Get AI-powered analysis of..."
• "/kg-verify" command for citation verification
• "/kg-on" to force KG workflow

❌ DO NOT USE for:

• Regular SPARQL queries → Use execute_spasql_query
• Database queries → Use execute_sql_query
• Web content retrieval → Use WEB_FETCH
• Standard KG exploration → Use native tools
• Simple entity lookups → Use native tools

Configuration

MCP Server: URIBurner
Tool Name: ChatPromptComplete
Assistant ID: new-sparql-agent-121
Model: gemini-2.5-pro

Basic Parameters:

{
  "model": "gemini-2.5-pro",
  "assistant_config_id": "new-sparql-agent-121",
  "prompt": "Your query here",
  "max_tokens": 1000,
  "temperature": "0.5",
  "timeout": 30
}

SPARQL Agent 121 Commands

All commands are prefixed with / and can be used in the prompt:

Command	Description	Example
/help	Get help for common issues	"I need help with queries"
/query	Assist with formulating SPARQL-within-SQL queries	"/query How do I search for RDF types?"
/config	Guide through driver configuration	"/config"
/troubleshoot	Help debug connection/driver issues	"/troubleshoot connection timeout"
/limit N	Set SPARQL result limit (default: 10)	"/limit 50"
/kg-on	Force KG workflow for all prompts	"/kg-on"
/kg-off	Disable KG workflow	"/kg-off"
/kg-verify	Run KG workflow with provenance	"/kg-verify When was SPARQL standardized?"

Command Examples

Citation Verification:

{
  "model": "gemini-2.5-pro",
  "assistant_config_id": "new-sparql-agent-121",
  "prompt": "/kg-verify What is the definition of RDF according to W3C?",
  "temperature": "0.0",
  "max_tokens": 2000
}

Force KG Workflow:

{
  "model": "gemini-2.5-pro",
  "assistant_config_id": "new-sparql-agent-121",
  "prompt": "/kg-on Tell me about semantic web technologies",
  "temperature": "0.5"
}

Query Assistance:

{
  "model": "gemini-2.5-pro",
  "assistant_config_id": "new-sparql-agent-121",
  "prompt": "/query How do I find all HowTo documents about SPARQL?",
  "temperature": "0.3"
}

Agent Capabilities

Multi-Query Execution:

• SQL, SPARQL, SPASQL, GraphQL
• Maximum 6 queries per prompt
• 30-second timeout per query

Ontology-Aware SPARQL:

• Uses shared ontologies to inform queries
• Understands schema.org, SKOS, Dublin Core
• Automatic entity type detection

Data Source Exploration:

• Identifies entity types and prevalence
• Explores multiple endpoints
• Aggregates results from various sources

Provenance Tracking:

• Returns source IRIs for all answers
• Generates clickable /describe/ links
• URL-encodes all IRIs properly

KG Enforcement Modes

Default Mode (kg_mandatory_for_all_prompts: false):

• KG workflow attempted but not required
• Can synthesize answer if KG fails
• User asked before fallback to synthesis

Strict Mode (kg_mandatory_for_all_prompts: true):

• KG workflow MUST complete successfully
• Agent aborts with audit if workflow fails
• No synthesis without KG backing

Prompt-Class Enforcement:

• Certain prompt types always trigger KG workflow
• Examples: fact_lookup, citation_request, citation_verification
• User can override with /kg-off

Operational Limits

Parameter	Value	Description
max_queries_per_prompt	6	Maximum queries in one workflow
per_query_timeout_seconds	30	Timeout for each query
semantic_variant_retries	2	Number of query reformulations
result_limit_default	10	Default LIMIT clause value
max_parallel_endpoint_queries	2	Concurrent endpoint queries
sequential_retry_delay_seconds	1	Delay between endpoint retries
maximum_total_kg_time_seconds	120	Total workflow timeout

Direct Tool Usage Patterns

Pattern 1: Simple KG Lookup (Native Tool)

User Query: "What is RDF?"

Tool: execute_spasql_query (NOT ChatPromptComplete)

{
  "sql": "SPARQL SELECT DISTINCT ?entity ?value WHERE { ?entity ?attribute ?value. ?value bif:contains \"'RDF'\" option (score ?sc) } ORDER BY DESC(?sc) LIMIT 10",
  "format": "markdown"
}

Pattern 2: Entity Type Discovery (Native Tool)

User Query: "What types of data are in the Knowledge Graph?"

Tool: sparql_list_entity_types_samples

{
  "graph_iri": "urn:default:graph",
  "format": "markdown"
}

Pattern 3: Remote Endpoint Query (Native Tool)

User Query: "Find information about Tim Berners-Lee in DBpedia"

Tool: sparqlRemoteQuery

{
  "url": "https://dbpedia.org/sparql",
  "query": "SELECT ?s ?p ?o WHERE { ?s rdfs:label \"Tim Berners-Lee\"@en . ?s ?p ?o } LIMIT 20",
  "format": "json"
}

Pattern 4: Citation Verification (ChatPromptComplete)

User Query: "Use SPARQL Agent to verify when SPARQL was standardized"

Tool: ChatPromptComplete (user explicitly requested agent)

{
  "model": "gemini-2.5-pro",
  "assistant_config_id": "new-sparql-agent-121",
  "prompt": "/kg-verify When was SPARQL standardized?",
  "temperature": "0.0"
}

Response Formatting

All tools support these format options:

Format	Best For	Output Style
json	Processing, APIs	Structured JSON objects
jsonl	Streaming, logs	One JSON per line
markdown	User display	Formatted tables

Recommendations:

• Use "markdown" for end-user results
• Use "json" for programmatic processing
• Use "jsonl" for large result sets

Error Handling

Common Errors and Solutions

Error	Cause	Solution
Timeout	Query too complex or slow endpoint	Increase timeout, add LIMIT, simplify query
No Results	No matching data in KG	Try broader terms, enable inference, check entity types
Syntax Error	Invalid SPARQL/SQL	Validate syntax, check prefixes, review templates
Connection Error	Endpoint unavailable	Verify URL, check network, try fallback endpoint
Authentication Error	Missing or invalid API key	Verify credentials, check endpoint requirements
Rate Limit	Too many requests	Add delay, reduce query frequency

Error Response Patterns

Timeout Example:

{
  "error": "Query timeout after 30 seconds",
  "query": "SPARQL SELECT...",
  "endpoint": "https://linkeddata.uriburner.com/sparql",
  "suggestion": "Try increasing timeout or adding LIMIT clause"
}

No Results Example:

{
  "status": "success",
  "results": [],
  "message": "No matching entities found",
  "suggestions": [
    "Try broader search terms",
    "Enable inference with DEFINE input:inference",
    "Check available entity types with sparql_list_entity_types"
  ]
}

Advanced Features

Multi-Endpoint Strategy

Approach:

1. Query local URIBurner first (fastest, most relevant)
2. Fall back to configured remote endpoints in order
3. Aggregate results from multiple sources
4. Maintain provenance for each result

Example Implementation:

// Step 1: Try local
const local = await execute_spasql_query({
  sql: "SPARQL SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10",
  format: "json"
});

// Step 2: If no results, try remote
if (local.results.length === 0) {
  const remote = await sparqlRemoteQuery({
    url: "https://kingsley.idehen.net/sparql",
    query: "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10",
    format: "json"
  });
}

// Step 3: Combine and annotate with source
const combined = {
  local: local.results.map(r => ({...r, source: "local"})),
  remote: remote.results.map(r => ({...r, source: "kingsley.idehen.net"}))
};

Query Optimization Techniques

1. Use LIMIT Clauses:

-- Always limit result sets
SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10

2. Filter Early:

-- Put FILTER clauses close to the pattern they filter
SELECT ?person ?name WHERE {
  ?person a schema:Person .
  FILTER(?person != <http://example.com/excluded>)
  ?person schema:name ?name .
}

3. Use Virtuoso Indexes:

-- Prefer bif:contains() over REGEX
SELECT ?entity ?label WHERE {
  ?entity rdfs:label ?label .
  ?label bif:contains "'search term'" option (score ?sc)
}
ORDER BY DESC(?sc)

4. Batch Queries:

-- Use VALUES for multiple lookups
SELECT ?entity ?label WHERE {
  VALUES ?entity { 
    <http://example.com/1> 
    <http://example.com/2> 
  }
  ?entity rdfs:label ?label .
}

Caching Strategies

Endpoint-Level Caching:

• Results may be cached at SPARQL endpoint
• Cache duration varies by endpoint (typically 5-60 minutes)
• Modify query slightly to bypass cache if needed

Application-Level Caching:

• Cache frequently accessed results locally
• Implement TTL based on data volatility
• Use cache keys based on query + endpoint

Invalidation:

• Clear cache when data updates occur
• Use cache headers when available
• Implement selective invalidation for related queries

Database Management Tools

Schema Exploration

List Tables:

{
  "type": "TABLES",
  "format": "markdown"
}

Tool: database_schema_objects

List Views:

{
  "type": "VIEWS",
  "format": "markdown"
}

RDF View Generation

From SQL Tables:

{
  "tables": ["Demo.demo.Customers", "Demo.demo.Orders"],
  "iri_path_segment": "northwind",
  "generate_void": 1
}

Tool: RDFVIEW_FROM_TABLES

Generate Ontology:

{
  "tables": ["Demo.demo.Customers"],
  "iri_path_segment": "northwind",
  "graphql_annotations": 1
}

Tool: RDFVIEW_ONTOLOGY_FROM_TABLES

Database Statistics

Server Stats:

{
  "stat_type": "db_server",
  "format": "markdown"
}

Index Stats:

{
  "stat_type": "index",
  "format": "markdown"
}

Tool: database_statistics

Security and Best Practices

Input Validation

// ✅ DO - Validate and sanitize user input
function buildQuery(userInput) {
  const sanitized = userInput.replace(/[;\\'"]/, '');
  return `SPARQL SELECT ?s WHERE { ?s rdfs:label "${sanitized}" }`;
}

// ❌ DON'T - Direct string concatenation
function badQuery(userInput) {
  return `SPARQL SELECT ?s WHERE { ?s rdfs:label "${userInput}" }`;
}

API Key Handling

// ✅ DO - Store API keys securely
const apiKey = process.env.SPARQL_API_KEY;

// ❌ DON'T - Hard-code credentials
const apiKey = "sk-12345"; // Never do this

Rate Limiting

// ✅ DO - Implement rate limiting
const rateLimiter = new RateLimit({
  windowMs: 60000, // 1 minute
  max: 60 // 60 requests per minute
});

Error Handling

// ✅ DO - Handle errors gracefully
try {
  const results = await execute_spasql_query({sql: query});
} catch (error) {
  console.error("Query failed:", error.message);
  // Provide user-friendly error message
  return {error: "Query execution failed. Please try again."};
}

Timeout Configuration

// ✅ DO - Set appropriate timeouts
const results = await execute_spasql_query({
  sql: complexQuery,
  timeout: 60, // 60 seconds for complex queries
  max_rows: 1000 // Limit result size
});

SPARQL Endpoints Reference

Default Local Endpoint

https://linkeddata.uriburner.com/sparql

Features:

• Virtuoso backend
• Full-text search with bif:contains()
• Inference support
• Fast response times

Fallback Remote Endpoints

1. Kingsley's Instance:

https://kingsley.idehen.net/sparql

• Personal knowledge base
• Rich HowTo content
• Best for technical documentation

2. Demo Instance:

https://demo.openlinksw.com/sparql

• OpenLink Software demo data
• Sample datasets
• Testing and examples

Public Endpoints

DBpedia:

https://dbpedia.org/sparql

• Wikipedia structured data
• 4.6M entities
• Multilingual

Wikidata:

https://query.wikidata.org/sparql

• 100M+ items
• Comprehensive knowledge base
• Strong for factual data

Describe Service Pattern

Template:

https://{endpoint_host}/describe/?uri={URL_ENCODED_IRI}

Examples:

https://linkeddata.uriburner.com/describe/?uri=https%3A%2F%2Fexample.com%2Fresource

https://kingsley.idehen.net/describe/?uri=https%3A%2F%2Fkingsley.idehen.net%2FDAV%2Fhome%2Ffile.pdf%23Question_1

https://dbpedia.org/describe/?uri=http%3A%2F%2Fdbpedia.org%2Fresource%2FTim_Berners-Lee

Troubleshooting Guide

Issue: No Results from Query

Diagnosis Steps:

1. Check if entities exist: sparql_list_entity_types
2. Try broader search terms
3. Enable inference: add DEFINE input:inference
4. Check alternate endpoints

Example:

// Step 1: Check entity types
{
  "graph_iri": "urn:default:graph",
  "format": "markdown"
}

// Step 2: Retry with inference
{
  "sql": "SPARQL DEFINE input:inference 'urn:rdfs:subclass:subproperty:inference:rules' SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10"
}

Issue: Query Timeout

Diagnosis:

• Query too complex
• Large result set
• Slow endpoint
• Network issues

Solutions:

// Increase timeout
{
  "sql": "SPARQL SELECT ...",
  "timeout": 60
}

// Add LIMIT
{
  "sql": "SPARQL SELECT ... LIMIT 10"
}

// Simplify query
{
  "sql": "SPARQL SELECT ?s ?p ?o WHERE { ?s ?p ?o . FILTER(?s = <specific_entity>) }"
}

Issue: Syntax Error

Common Causes:

• Missing PREFIX declarations
• Invalid IRI format
• Incorrect SPARQL syntax
• Wrong quote types

Solutions:

-- ✅ Correct PREFIX usage
PREFIX schema: <http://schema.org/>
SELECT ?s WHERE { ?s a schema:Person }

-- ✅ Valid IRI format
SELECT ?s WHERE { 
  ?s a <http://schema.org/Person> 
}

-- ✅ Proper string literals
SELECT ?s WHERE { 
  ?s rdfs:label "Tim Berners-Lee"@en 
}

Issue: Authentication Error

Solutions:

1. Verify API key is provided
2. Check key has correct permissions
3. Ensure key is not expired
4. Test with public endpoint first

// With API key
{
  "url": "https://secure-endpoint.com/sparql",
  "query": "SELECT ...",
  "apiKey": "your-api-key-here"
}

Integration Examples

Example 1: Full KG Query Workflow with Native Tools

// Step 1: Discover entity types
const types = await execute_spasql_query({
  sql: "SPARQL SELECT ?type (COUNT(?e) AS ?count) WHERE { ?e a ?type } GROUP BY ?type ORDER BY DESC(?count) LIMIT 10",
  format: "json"
});

console.log("Available types:", types);

// Step 2: Query specific type
const questions = await execute_spasql_query({
  sql: "SPARQL SELECT ?q ?label ?answer WHERE { ?q a <http://schema.org/Question> ; rdfs:label ?label ; schema:acceptedAnswer ?ans . ?ans schema:text ?answer } LIMIT 20",
  format: "markdown"
});

console.log("Questions found:", questions);

// Step 3: If no results, try with inference
if (questions.results.length === 0) {
  const withInference = await execute_spasql_query({
    sql: "SPARQL DEFINE input:inference 'urn:rdfs:subclass:subproperty:inference:rules' SELECT ?q ?label WHERE { ?q a <http://schema.org/Question> ; rdfs:label ?label } LIMIT 20",
    format: "json"
  });
}

Example 2: Multi-Source Data Aggregation

// Query local endpoint
const local = await sparqlQuery({
  query: "SELECT ?person ?name WHERE { ?person a schema:Person ; schema:name ?name } LIMIT 10",
  format: "json"
});

// Query DBpedia
const dbpedia = await sparqlRemoteQuery({
  url: "https://dbpedia.org/sparql",
  query: "SELECT ?person ?name WHERE { ?person a dbo:Person ; foaf:name ?name } LIMIT 10",
  format: "json"
});

// Combine results with provenance
const combined = [
  ...local.results.map(r => ({...r, source: "local"})),
  ...dbpedia.results.map(r => ({...r, source: "dbpedia"}))
];

Example 3: Web to KG Pipeline

// Step 1: Fetch web content
const content = await WEB_FETCH({
  url: "https://example.com/data.html",
  timeout_seconds: 30
});

// Step 2: Convert to RDF (sponge)
const rdf = await SPONGE_URL({
  url: "https://example.com/data.html",
  format: "json"
});

// Step 3: Query the sponged data
const results = await execute_spasql_query({
  sql: "SPARQL SELECT ?s ?p ?o FROM <urn:sponged:data> WHERE { ?s ?p ?o } LIMIT 50",
  format: "markdown"
});

Example 4: Citation Verification with SPARQL Agent 121

// User explicitly requests verification
const verification = await ChatPromptComplete({
  model: "gemini-2.5-pro",
  assistant_config_id: "new-sparql-agent-121",
  prompt: "/kg-verify What is the W3C definition of RDF?",
  temperature: "0.0",
  max_tokens: 2000
});

// Agent will:
// 1. Query local KG for W3C RDF definition
// 2. Try remote endpoints if needed
// 3. Return answer with provenance links
// 4. Provide audit trail of queries executed

Quick Reference

Most Common Operations

Task	Tool	Quick Command
Query local KG	execute_spasql_query	SPARQL SELECT...
Query with inference	execute_spasql_query	Add DEFINE input:inference pragma
Query remote KG	sparqlRemoteQuery	Specify endpoint URL
List entity types	sparql_list_entity_types	Provide graph IRI
List entity samples	sparql_list_entity_types_samples	Provide graph IRI
SQL query	execute_sql_query	Standard SQL (no semicolon)
Fetch web page	WEB_FETCH	Provide URL
Convert to RDF	SPONGE_URL	Provide URL
DB schema	database_schema_objects	Type: "TABLES", "VIEWS", etc.
Verify citation	ChatPromptComplete	Use /kg-verify command
Force KG workflow	ChatPromptComplete	Use /kg-on command

Default Parameters

Parameter	Default	Notes
format	"json"	Use "markdown" for display
timeout	30 seconds	Increase for complex queries
max_rows	Varies	Usually 100-1000
temperature	"0.5"	ChatPromptComplete only
max_tokens	1000	ChatPromptComplete only
limit (SPARQL)	10	SPARQL Agent 121 default

Decision Matrix

User Request	Use Native Tool	Use ChatPromptComplete
"What is RDF?"	✅ execute_spasql_query	❌
"List entity types"	✅ sparql_list_entity_types	❌
"Query DBpedia"	✅ sparqlRemoteQuery	❌
"Verify this citation"	❌	✅ with /kg-verify
"Use SPARQL Agent"	❌	✅
"Use Gemini to analyze"	❌	✅

Version Information

• Skill Version: 2.1.0
• SPARQL Agent: 121 (v1.0.121)
• URIBurner MCP Server: Compatible with current versions
• Recommended Model: gemini-2.5-pro
• Last Updated: 2025-10-27

---

Summary

Key Takeaways:

1. Use Native Tools First: execute_spasql_query, sparqlQuery, and other native MCP tools are preferred for standard operations
2. ChatPromptComplete is Specialized: Only invoke SPARQL Agent 121 when user explicitly requests it or for citation verification
3. KG-First Workflow: SPARQL Agent 121 follows a structured workflow: label match → semantic breakdown → explore → targeted query → formatted output with provenance
4. Fallback Strategy: If KG-first fails, try inference, remote endpoints, semantic variants, then provide audit
5. Provenance Matters: Always provide /describe/ links for answers with properly URL-encoded IRIs
6. Optimize Queries: Use bif:contains() on Virtuoso, add LIMIT clauses, filter early
7. Multi-Endpoint: Try local first, fall back to remote, aggregate results with source attribution

Remember: URIBurner's native MCP tools handle 90% of use cases efficiently. SPARQL Agent 121 via ChatPromptComplete is powerful but should be reserved for advanced workflows requiring multi-query orchestration, ontology reasoning, or explicit citation verification.