Devtu Auto Discover Apis

Automated Life Science API Discovery & Tool Creation

Discover, create, validate, and integrate life science APIs into ToolUniverse through fully automated workflows with human review checkpoints.

When to Use This Skill

Use this skill when:

• Expanding ToolUniverse coverage in underrepresented domains
• Systematically discovering new life science APIs and databases
• Building a batch of tools from multiple APIs at once
• Identifying gaps in current ToolUniverse tool coverage
• Automating the tool creation pipeline from discovery to PR
• Adding emerging APIs from recent publications or releases

Triggers: "find new APIs", "expand tool coverage", "discover missing tools", "add APIs for [domain]"

---

Table of Contents

1. [Overview](#overview)
2. [Four-Phase Workflow](#four-phase-workflow)
3. [Phase 1: Discovery & Gap Analysis](#phase-1-discovery--gap-analysis)
4. [Phase 2: Tool Creation](#phase-2-tool-creation)
5. [Phase 3: Validation](#phase-3-validation)
6. [Phase 4: Integration](#phase-4-integration)
7. [Configuration Options](#configuration-options)
8. [Output Artifacts](#output-artifacts)
9. [Quality Gates](#quality-gates)
10. [Common Patterns](#common-patterns)
11. [Troubleshooting](#troubleshooting)

---

Overview

This skill orchestrates a complete pipeline:

Gap Analysis → API Discovery → Tool Creation → Validation → Integration
     ↓              ↓               ↓              ↓            ↓
  Coverage      Web Search      devtu-create   devtu-fix    Git PR
  Report        + Docs          patterns       validation   Ready

Automation Level: Fully automated with human approval gates at:

• After gap analysis (approve focus areas)
• After tool creation (review generated tools)
• Before PR submission (final review)

Authentication Handling: Supports public APIs, API keys, OAuth, and complex authentication schemes

Output: Working tool files (.py + .json), validation reports, discovery documentation, and integration-ready PRs

---

Four-Phase Workflow

Phase 1: Discovery & Gap Analysis (15-30 minutes)

Objectives:

1. Analyze current ToolUniverse tools by domain/category
2. Identify underrepresented areas (gap domains)
3. Search web for APIs in gap domains
4. Scrape API documentation for endpoints and schemas
5. Generate discovery report with prioritized candidates

Key Activities:

• Load ToolUniverse and categorize existing tools
• Calculate coverage metrics by domain
• Execute targeted web searches for gaps
• Extract API metadata from documentation
• Score APIs by quality, coverage, and integration feasibility

Output: discovery_report.md with prioritized API candidates

Phase 2: Tool Creation (30-60 minutes per API)

Objectives:

1. Design tool architecture (multi-operation vs single-operation)
2. Generate Python tool classes following devtu-create-tool patterns
3. Create JSON configurations with proper schemas
4. Handle authentication (API keys, OAuth, tokens)
5. Generate realistic test examples

Key Activities:

• Map API endpoints to ToolUniverse operations
• Generate tool class with error handling
• Create return schemas with oneOf + data wrapper structure
• Find real test IDs from API documentation
• Register in default_config.py

Output: .py and .json files for each tool

Phase 3: Validation (10-20 minutes per tool)

Objectives:

1. Run automated schema validation
2. Execute integration tests with real API calls
3. Verify devtu compliance (6-step checklist)
4. Check tool loading in ToolUniverse
5. Generate validation reports

Key Activities:

• Run python scripts/test_new_tools.py -v
• Verify return_schema has oneOf structure
• Test examples use real IDs (no placeholders)
• Confirm tools load into ToolUniverse registry
• Apply devtu-fix-tool patterns for any failures

Output: validation_report.md with pass/fail metrics

Phase 4: Integration (5-10 minutes)

Objectives:

1. Create git branch for new tools
2. Commit tools with descriptive messages
3. Generate PR with full documentation
4. Include discovery notes and validation results

Key Activities:

• Create feature branch: feature/add--tools
• Commit tool files with Co-Authored-By Claude
• Write PR description with API info, tool list, validation results
• Push to remote and create PR

Output: Integration-ready PR for human review

---

Phase 1: Discovery & Gap Analysis

Step 1.1: Analyze Current Coverage

Load and categorize existing tools:

1. Initialize ToolUniverse and load all tools
2. Extract tool names and descriptions
3. Categorize by domain using keywords:

• Genomics: sequence, genome, gene, variant, SNP
• Proteomics: protein, structure, PDB, fold, domain
• Drug Discovery: drug, compound, molecule, ligand, ADMET
• Clinical: disease, patient, trial, phenotype, diagnosis
• Omics: expression, transcriptome, metabolome, proteome
• Imaging: microscopy, imaging, scan, radiology
• Literature: pubmed, citation, publication, article
• Pathways: pathway, network, interaction, signaling
• Systems Biology: model, simulation, flux, dynamics

1. Count tools per category
2. Calculate coverage percentages

Output: Coverage matrix with tool counts

Step 1.2: Identify Gap Domains

Find underrepresented areas:

Gap Detection Criteria:

• Critical Gap: Dict[str, Any]:

"""Route to operation handler.""" operation = arguments.get("operation")

if not operation: return {"status": "error", "error": "Missing required parameter: operation"}

# Route to handlers if operation == "operation1": return self.operation1(arguments) elif operation == "operation2": return self.operation2(arguments) else: return {"status": "error", "error": f"Unknown operation: {operation}"}

def _operation1(self, arguments: Dict[str, Any]) -> Dict[str, Any]: """Description of operation1.""" # Validate required parameters param1 = arguments.get("param1") if not param1: return {"status": "error", "error": "Missing required parameter: param1"}

try: # Build request headers = {} if self.apikey: headers["Authorization"] = f"Bearer {self.apikey}"

# Make API call response = requests.get( f"{self.BASEURL}/endpoint", params={"param1": param1}, headers=headers, timeout=30 ) response.raisefor_status()

# Parse response data = response.json()

# Return with data wrapper return { "status": "success", "data": data.get("results", []), "metadata": { "total": data.get("total", 0), "source": "[API Name]" } }

except requests.exceptions.Timeout: return {"status": "error", "error": "API timeout after 30 seconds"} except requests.exceptions.HTTPError as e: return {"status": "error", "error": f"HTTP {e.response.status_code}: {e.response.text[:200]}"} except Exception as e: return {"status": "error", "error": f"Unexpected error: {str(e)}"}

**Critical Requirements**:
- Always return `{"status": "success|error", "data": {...}}`
- NEVER raise exceptions in `run()` method
- Set timeout on all HTTP requests (30s recommended)
- Handle specific exceptions (Timeout, HTTPError, ConnectionError)
- Include helpful error messages with context

### Step 2.3: Generate JSON Configuration

**Template Structure**:

```json
[
  {
    "name": "[APIName]_operation1",
    "class": "[APIName]Tool",
    "description": "[What it does]. Returns [data format]. [Input details]. Example: [usage example]. [Special notes].",
    "parameter": {
      "type": "object",
      "required": ["operation", "param1"],
      "properties": {
        "operation": {
          "const": "operation1",
          "description": "Operation identifier (fixed)"
        },
        "param1": {
          "type": "string",
          "description": "Description of param1 with format/constraints"
        }
      }
    },
    "return_schema": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {"type": "string"},
                  "name": {"type": "string"}
                }
              }
            },
            "metadata": {
              "type": "object",
              "properties": {
                "total": {"type": "integer"},
                "source": {"type": "string"}
              }
            }
          }
        },
        {
          "type": "object",
          "properties": {
            "error": {"type": "string"}
          },
          "required": ["error"]
        }
      ]
    },
    "test_examples": [
      {
        "operation": "operation1",
        "param1": "real_value_from_api_docs"
      }
    ]
  }
]

Critical Requirements:

• return_schema MUST have oneOf: Success schema + error schema
• Success schema MUST have data field: Top-level data wrapper required
• testexamples MUST use real IDs: NO "TEST", "DUMMY", "PLACEHOLDER", "example*"
• Tool name ≤55 characters: For MCP compatibility
• Description 150-250 chars: Include what, format, example, special notes

Step 2.4: Handle Authentication

Authentication Patterns:

Pattern 1: Public API (No Auth)

# No special handling needed
response = requests.get(url, params=params, timeout=30)

Pattern 2: API Key (Optional)

# In __init__
self.api_key = os.environ.get("API_KEY_NAME", "")

# In JSON config
"optional_api_keys": ["API_KEY_NAME"],
"description": "... Rate limits: 3 req/sec without key, 10 req/sec with API_KEY_NAME."

# In request
headers = {}
if self.api_key:
    headers["Authorization"] = f"Bearer {self.api_key}"
response = requests.get(url, headers=headers, timeout=30)

Pattern 3: API Key (Required)

# In __init__
self.api_key = os.environ.get("API_KEY_NAME")
if not self.api_key:
    raise ValueError("API_KEY_NAME environment variable required")

# In JSON config
"required_api_keys": ["API_KEY_NAME"]

# In request
headers = {"Authorization": f"Bearer {self.api_key}"}
response = requests.get(url, headers=headers, timeout=30)

Pattern 4: OAuth (Complex)

# Document in skill: requires manual OAuth setup
# Store tokens in environment
# Implement token refresh logic
# Include example OAuth flow in documentation

Step 2.5: Find Real Test Examples

Strategy: List → Get pattern

1. Find List Endpoint: Identify endpoint that lists resources
2. Extract Real ID: Call list endpoint, extract first valid ID
3. Test Get Endpoint: Verify ID works in detail endpoint
4. Document in test_examples: Use discovered real ID

Example Process:

1. API docs show: GET /items → returns [{id: "ABC123", ...}]
2. Make request: curl https://api.example.com/items
3. Extract: id = "ABC123"
4. Verify: curl https://api.example.com/items/ABC123 → 200 OK
5. Use in test_examples: {"operation": "get_item", "item_id": "ABC123"}

Fallback: Search API documentation examples, tutorial code, or forum posts for real IDs

Step 2.6: Register in default_config.py

Add to src/tooluniverse/default_config.py:

TOOLS_CONFIGS = {
    # ... existing entries ...
    "[api_category]": os.path.join(current_dir, "data", "[api_name]_tools.json"),
}

Critical: This step is commonly missed! Tools won't load without it.

---

Phase 3: Validation

Step 3.1: Schema Validation

Check return_schema structure:

import json

with open("src/tooluniverse/data/[api_name]_tools.json") as f:
    tools = json.load(f)

for tool in tools:
    schema = tool.get("return_schema", {})

    # Must have oneOf
    assert "oneOf" in schema, f"{tool['name']}: Missing oneOf in return_schema"

    # oneOf must have 2 schemas (success + error)
    assert len(schema["oneOf"]) == 2, f"{tool['name']}: oneOf must have 2 schemas"

    # Success schema must have 'data' field
    success_schema = schema["oneOf"][0]
    assert "properties" in success_schema, f"{tool['name']}: Missing properties in success schema"
    assert "data" in success_schema["properties"], f"{tool['name']}: Missing 'data' field in success schema"

    print(f"✅ {tool['name']}: Schema valid")

Step 3.2: Test Example Validation

Check for placeholder values:

PLACEHOLDER_PATTERNS = [
    "test", "dummy", "placeholder", "example", "sample",
    "xxx", "temp", "fake", "mock", "your_"
]

for tool in tools:
    examples = tool.get("test_examples", [])

    for i, example in enumerate(examples):
        for key, value in example.items():
            if isinstance(value, str):
                value_lower = value.lower()
                if any(pattern in value_lower for pattern in PLACEHOLDER_PATTERNS):
                    print(f"❌ {tool['name']}: test_examples[{i}][{key}] contains placeholder: {value}")
                else:
                    print(f"✅ {tool['name']}: test_examples[{i}][{key}] appears real")

Step 3.3: Tool Loading Verification

Verify three-step registration:

import sys
sys.path.insert(0, 'src')

# Step 1: Check class registered
from tooluniverse.tool_registry import get_tool_registry
import tooluniverse.[api_name]_tool
registry = get_tool_registry()
assert "[APIName]Tool" in registry, "❌ Step 1 FAILED: Class not registered"
print("✅ Step 1: Class registered")

# Step 2: Check config registered
from tooluniverse.default_config import TOOLS_CONFIGS
assert "[api_category]" in TOOLS_CONFIGS, "❌ Step 2 FAILED: Config not in default_config.py"
print("✅ Step 2: Config registered")

# Step 3: Check wrappers generated
from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()
assert hasattr(tu.tools, '[APIName]_operation1'), "❌ Step 3 FAILED: Wrapper not generated"
print("✅ Step 3: Wrappers generated")

print("✅ All registration steps complete!")

Step 3.4: Integration Tests

Run testnewtools.py:

# Test specific tools
python scripts/test_new_tools.py [api_name] -v

# Expected output:
# Testing [APIName]_operation1...
# ✅ PASS - Schema valid
#
# Results:
# Total: 3 tests
# Passed: 3 (100.0%)
# Failed: 0
# Schema invalid: 0

Handle failures:

• 404 ERROR: Invalid test example ID → find real ID
• Schema Mismatch: return_schema doesn't match response → fix schema
• Timeout: API slow/down → increase timeout or add retry
• Parameter Error: Wrong parameter names → verify with API docs

Step 3.5: Generate Validation Report

Report Structure:

# Validation Report: [API Name]
Generated: [Timestamp]

## Summary
- Total tools: X
- Passed: Y (Z%)
- Failed: N
- Schema issues: M

## Tool Loading
- [x] Class registered in tool_registry
- [x] Config registered in default_config.py
- [x] Wrappers generated in tools/

## Schema Validation
- [x] All tools have oneOf structure
- [x] All success schemas have data wrapper
- [x] All error schemas have error field

## Test Examples
- [x] No placeholder values detected
- [x] All examples use real IDs

## Integration Tests

### [APIName]_operation1
- Status: ✅ PASS
- Response time: 1.2s
- Schema: Valid

### [APIName]_operation2
- Status: ✅ PASS
- Response time: 0.8s
- Schema: Valid

## Issues Found
None - all tests passing!

## devtu Compliance Checklist
1. [x] Tool Loading: Verified
2. [x] API Verification: Checked against docs
3. [x] Error Pattern Detection: None found
4. [x] Schema Validation: All valid
5. [x] Test Examples: All

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Zaoqu-Liu](https://github.com/Zaoqu-Liu)
- **Source:** [Zaoqu-Liu/ScienceClaw](https://github.com/Zaoqu-Liu/ScienceClaw)
- **License:** MIT

Install and usage instructions live in the source repository linked above.