tpmjs/packages/tools/official/blocks.yml

project:
  name: "tpmjs-official-tools"
  domain: "tpmjs.tools"

targets:
  kind: "block"
  discover:
    root: "."

# =============================================================================
# PHILOSOPHY - Core principles that guide all tool development
# =============================================================================
philosophy:
  - "Every tool MUST be a working, production-ready implementation - no stubs, no TODOs"
  - "Tools use AI SDK v6 tool() + jsonSchema() pattern exclusively"
  - "Each tool does ONE thing exceptionally well (single-shot, one call in, one result out)"
  - "Tools return structured, typed outputs that agents can reliably parse"
  - "Error handling is explicit - throw meaningful errors, never silently fail"
  - "All async operations use proper error boundaries"
  - "Dependencies are minimal and production-stable (no alpha/beta packages unless necessary)"
  - "Tools are deterministic where possible - same input yields same output"
  - "Network I/O is async but tools are single-shot (no streaming, no multi-step orchestration inside)"

# =============================================================================
# DOMAIN - Entities, signals, and measures that define the problem space
# =============================================================================
domain:
  entities:
    # -------------------------------------------------------------------------
    # Core web entities
    # -------------------------------------------------------------------------
    url:
      fields: [href, domain, protocol, path, query, fragment]
      description: "A fully qualified URL with parsed components"

    webpage:
      fields: [url, title, html, text, metadata]
      description: "A fetched webpage with extracted content"

    redirect_chain:
      fields: [steps, finalUrl, statusCodes]
      description: "Full redirect trace from origin to destination"

    meta_tags:
      fields: [title, description, canonical, ogTags, twitterTags]
      description: "Extracted metadata for previews and SEO"

    json_ld:
      fields: [type, data, context]
      description: "Structured data extracted from JSON-LD blocks"

    link_catalog:
      fields: [internal, external, anchors, resolved]
      description: "Categorized links from a page"

    html_table:
      fields: [headers, rows, caption]
      description: "Normalized table data from HTML"

    # -------------------------------------------------------------------------
    # Research & content entities
    # -------------------------------------------------------------------------
    text_content:
      fields: [raw, sentences, paragraphs, wordCount]
      description: "Processed text with structural analysis"

    claim:
      fields: [statement, confidence, needsCitation, category, suggestedEvidence]
      description: "A factual assertion that can be verified"
      categories: [factual, statistical, quote, attribution, prediction]

    timeline_event:
      fields: [date, description, confidence, source, dateType]
      description: "A dated event with provenance"
      dateTypes: [specific, partial, relative, range]

    page_brief:
      fields: [url, title, summary, keyPoints, claims]
      description: "A summarized view of a webpage"

    comparison_result:
      fields: [agreements, conflicts, uniqueToA, uniqueToB, similarity]
      description: "Side-by-side analysis of two sources"

    credibility_score:
      fields: [score, signals, warnings, recommendations, confidence]
      description: "Trust assessment of a source"

    claim_checklist:
      fields: [claims, citedCount, uncitedCount, byPriority]
      description: "Extracted claims with citation status"

    timeline:
      fields: [events, dateRange, gaps, eventCount]
      description: "Chronological event sequence"

    rss_feed:
      fields: [title, link, items, lastBuildDate]
      description: "Parsed RSS/Atom feed with normalized items"

    rss_item:
      fields: [title, link, pubDate, summary, guid]
      description: "Individual feed item"

    sitemap:
      fields: [urls, isSitemapIndex, lastmod]
      description: "Parsed sitemap with URLs for crawling"

    robots_policy:
      fields: [userAgent, allow, disallow, crawlDelay, sitemaps]
      description: "Parsed robots.txt rules"

    # -------------------------------------------------------------------------
    # Document & deliverable entities
    # -------------------------------------------------------------------------
    executive_brief:
      fields: [whatHappened, soWhat, recommendation, audience]
      description: "Structured exec summary"

    runbook:
      fields: [prechecks, steps, rollback, verify, owners]
      description: "Operational procedure document"

    postmortem:
      fields: [timeline, impact, rootCause, hypotheses, actions, lessons]
      description: "Incident analysis document"

    faq:
      fields: [items, categories]
      description: "Question and answer pairs"

    glossary:
      fields: [terms, domain]
      description: "Domain terms with definitions"

    toc:
      fields: [entries, maxDepth]
      description: "Table of contents from headings"

    meeting_minutes:
      fields: [attendees, decisions, actionItems, notes]
      description: "Structured meeting record"

    adr:
      fields: [title, context, decision, alternatives, consequences, status]
      description: "Architecture Decision Record"

    changelog_entry:
      fields: [version, date, added, changed, fixed, removed]
      description: "Grouped change notes"

    release_notes:
      fields: [version, highlights, breaking, upgrades, audience]
      description: "User-facing release documentation"

    prd:
      fields: [problem, goals, nonGoals, ux, metrics, risks, rollout]
      description: "Product Requirements Document outline"

    acceptance_criteria:
      fields: [given, when, then, notes]
      description: "Testable requirement specification"

    test_plan:
      fields: [scenarios, steps, expected, priority, coverage]
      description: "QA test matrix"

    blog_post:
      fields: [frontmatter, content, formattedOutput]
      description: "A complete blog post with metadata"

    # -------------------------------------------------------------------------
    # Data & transform entities
    # -------------------------------------------------------------------------
    csv_data:
      fields: [headers, rows, delimiter]
      description: "Parsed CSV with type inference"

    yaml_data:
      fields: [data, comments]
      description: "Parsed YAML as JSON"

    json_data:
      fields: [data, repaired]
      description: "Parsed or repaired JSON"

    row_set:
      fields: [rows, schema, count]
      description: "Tabular data for operations"

    validation_result:
      fields: [valid, errors, warnings]
      description: "Schema validation outcome"

    text_chunks:
      fields: [chunks, totalLength, overlap]
      description: "Text split for processing"

    pivot_result:
      fields: [rows, index, columns, values]
      description: "Pivoted data transformation"

    # -------------------------------------------------------------------------
    # Engineering & ops entities
    # -------------------------------------------------------------------------
    diff_result:
      fields: [hunks, additions, deletions, unified]
      description: "Text difference analysis"

    stacktrace:
      fields: [frames, language, appFrames, libFrames]
      description: "Parsed stack trace"

    error_triage:
      fields: [category, likelyCause, nextChecks, confidence]
      description: "Error classification result"

    commit_message:
      fields: [type, scope, subject, body, breaking]
      description: "Conventional commit structure"

    env_var_docs:
      fields: [vars, required, optional, examples]
      description: "Environment variable documentation"

    openapi_snippet:
      fields: [paths, components, info]
      description: "Minimal OpenAPI specification"

    api_docs:
      fields: [auth, errors, endpoints, examples]
      description: "API documentation structure"

    dependency_audit:
      fields: [duplicates, suspicious, heavy, recommendations]
      description: "Package dependency analysis"

    config_normalized:
      fields: [config, applied, defaults]
      description: "Normalized configuration object"

    release_checklist:
      fields: [items, stack, critical, optional]
      description: "Pre-release verification list"

    # -------------------------------------------------------------------------
    # Ops entities
    # -------------------------------------------------------------------------
    monitoring_gaps:
      fields: [missing, recommended, coverage]
      description: "Monitoring gap analysis"

    slo_draft:
      fields: [slis, targets, alerts, rationale]
      description: "Service Level Objective specification"

    action_item:
      fields: [action, owner, dueDate, priority, status]
      description: "Extracted action from text"

    # -------------------------------------------------------------------------
    # Security & compliance entities
    # -------------------------------------------------------------------------
    url_risk:
      fields: [riskLevel, signals, punycode, homoglyph, tldRisk]
      description: "URL phishing risk assessment"

    secret_scan:
      fields: [findings, types, locations, severity]
      description: "Detected secrets in text"

    redaction_result:
      fields: [redacted, report, fingerprints]
      description: "Sanitized text with redaction log"

    csp_header:
      fields: [directives, headerString]
      description: "Content Security Policy"

    hardening_checklist:
      fields: [items, category, priority, stack]
      description: "Security hardening tasks"

    data_classification:
      fields: [fields, pii, sensitive, public]
      description: "Data sensitivity labels"

    retention_policy:
      fields: [datasets, retention, deletion, legal]
      description: "Data retention specification"

    dpia_outline:
      fields: [purpose, risks, mitigations, necessity]
      description: "Data Protection Impact Assessment"

    access_matrix:
      fields: [roles, resources, permissions]
      description: "RBAC permission matrix"

    sbom:
      fields: [packages, versions, licenses, sources]
      description: "Software Bill of Materials"

    # -------------------------------------------------------------------------
    # Statistics & quantitative entities
    # -------------------------------------------------------------------------
    confidence_interval:
      fields: [estimate, lower, upper, level, method]
      description: "Statistical confidence interval"

    hypothesis_test:
      fields: [statistic, pValue, significant, method]
      description: "Statistical test result"

    effect_size:
      fields: [measure, value, interpretation, type]
      description: "Effect size calculation"

    regression_result:
      fields: [coefficients, rSquared, residuals, diagnostics]
      description: "Regression model output"

    time_series_decomposition:
      fields: [trend, seasonal, residual, period]
      description: "Decomposed time series"

    anomaly_result:
      fields: [anomalies, threshold, method, scores]
      description: "Detected anomalies"

    posterior:
      fields: [distribution, mean, credibleInterval, prior]
      description: "Bayesian posterior estimate"

    did_estimate:
      fields: [effect, standardError, assumptions, parallel]
      description: "Difference-in-differences result"

    # -------------------------------------------------------------------------
    # Sandbox & execution entities
    # -------------------------------------------------------------------------
    sprite:
      fields: [name, status, createdAt, runtime, filesystem]
      description: "Isolated Linux sandbox environment"

    sprite_list:
      fields: [sprites, count]
      description: "Collection of sprites with metadata"

    exec_result:
      fields: [exitCode, stdout, stderr, duration]
      description: "Command execution result from a sprite"

    exec_session:
      fields: [id, status, startedAt, command]
      description: "Active execution session in a sprite"

    checkpoint:
      fields: [id, name, createdAt, size]
      description: "Point-in-time snapshot of sprite state"

    checkpoint_list:
      fields: [checkpoints, count]
      description: "Collection of checkpoints for a sprite"

    network_policy:
      fields: [mode, allowedDomains, rules]
      description: "DNS-based network filtering configuration"

    # -------------------------------------------------------------------------
    # Code execution entities (unsandbox)
    # -------------------------------------------------------------------------
    code_execution_result:
      fields: [stdout, stderr, exitCode, duration, language]
      description: "Result of executing code in a sandbox"

    code_execution_job:
      fields: [jobId, status, createdAt, language]
      description: "Async code execution job reference"

    code_job_result:
      fields: [jobId, status, stdout, stderr, exitCode, duration, error]
      description: "Completed job result with output"

    input_file:
      fields: [filename, content]
      description: "File to make available in sandbox /tmp/input/"

    compiled_artifact:
      fields: [binary, format, size]
      description: "Compiled binary artifact from code execution"

    wasm_artifact:
      fields: [wasm, format, size]
      description: "WebAssembly compiled artifact"

    # -------------------------------------------------------------------------
    # exe.dev VM management entities
    # -------------------------------------------------------------------------
    exe_vm:
      fields: [name, image, status, createdAt, url]
      description: "An exe.dev virtual machine instance"

    exe_vm_list:
      fields: [vms, count]
      description: "List of exe.dev VMs"

    exe_share_info:
      fields: [vm, isPublic, port, users, links]
      description: "Sharing configuration for an exe.dev VM"

    exe_share_link:
      fields: [token, url, createdAt]
      description: "A shareable link for VM access"

    exe_user_info:
      fields: [email, sshKeys]
      description: "exe.dev user account information"

    exe_command_result:
      fields: [stdout, stderr, exitCode]
      description: "Result of executing a command on an exe.dev VM"

    # -------------------------------------------------------------------------
    # HLLM entities
    # -------------------------------------------------------------------------
    hllm_topology_result:
      fields: [id, status, output, tokens, duration, steps]
      description: "Result of executing an HLLM topology"

    hllm_session:
      fields: [id, title, createdAt, updatedAt, messageCount]
      description: "An HLLM chat session"

    hllm_message:
      fields: [id, role, content, createdAt]
      description: "A message in an HLLM chat session"

    hllm_prompt:
      fields: [id, name, content, description, category, tags, usageCount]
      description: "A prompt in the HLLM prompt library"

    hllm_user_profile:
      fields: [id, email, name, avatar, preferences]
      description: "HLLM user profile information"

    hllm_user_stats:
      fields: [totalExecutions, totalTokens, totalSessions, totalPrompts, topologyBreakdown]
      description: "HLLM user usage statistics"

    hllm_env_var:
      fields: [key, value, createdAt, updatedAt]
      description: "A TPMJS environment variable in HLLM"

    hllm_file:
      fields: [id, name, size, mimeType, url, createdAt]
      description: "An uploaded file in HLLM"

    hllm_model:
      fields: [id, name, provider, contextWindow, inputPricing, outputPricing, capabilities]
      description: "An available AI model in HLLM"

    hllm_execution_log:
      fields: [id, topologyType, status, inputTokens, outputTokens, duration, error]
      description: "An execution log entry in HLLM"

    hllm_agent_metrics:
      fields: [totalRequests, successRate, averageLatency, tokenUsage, topologyBreakdown]
      description: "HLLM agent performance metrics"

    hllm_tool_info:
      fields: [id, name, description, package, parameters]
      description: "Information about a TPMJS tool in HLLM"

    hllm_api_key:
      fields: [id, name, keyHint, createdAt, lastUsedAt]
      description: "An HLLM API key"

    # -------------------------------------------------------------------------
    # Agent & workflow entities
    # -------------------------------------------------------------------------
    recipe:
      fields: [name, steps, params, artifacts, checks]
      description: "Canonical workflow specification"

    workflow:
      fields: [steps, inputs, outputs, cost]
      description: "Executable step sequence"

    routing_ruleset:
      fields: [rules, predicates, actions, fallback]
      description: "Intent to tool routing rules"

    eval_fixture:
      fields: [input, expectedCalls, context, tags]
      description: "Evaluation test case"

    coverage_report:
      fields: [domains, artifacts, gaps, score]
      description: "Recipe coverage analysis"

    novelty_score:
      fields: [score, similar, unique, method]
      description: "Workflow uniqueness measure"

    cost_estimate:
      fields: [steps, bytes, networkCalls, complexity]
      description: "Workflow resource estimate"

    guardrail_policy:
      fields: [allowedDomains, maxBytes, redaction, refusals]
      description: "Operational safety constraints"

    output_contract:
      fields: [schema, limits, enforced]
      description: "Tool output validation spec"

    workflow_skeleton:
      fields: [steps, rationale, alternatives]
      description: "Proposed workflow structure"

    workflow_explanation:
      fields: [steps, whyEach, outputs]
      description: "Human-readable workflow description"

    publish_manifest:
      fields: [tags, categories, readme, metadata]
      description: "Recipe publication metadata"

  # ---------------------------------------------------------------------------
  # Signals - Observable indicators extracted from data
  # ---------------------------------------------------------------------------
  signals:
    credibility:
      description: "Trustworthiness indicators for a source"
      extraction_hints:
        - "HTTPS vs HTTP"
        - "Domain reputation (.edu, .gov, major news)"
        - "Author byline and bio present"
        - "Publication date visible"
        - "Citations and references"
        - "Contact information available"

    readability:
      description: "How accessible the content is"
      extraction_hints:
        - "Sentence length and complexity"
        - "Technical jargon density"
        - "Clear paragraph structure"
        - "Heading hierarchy"

    claim_strength:
      description: "How verifiable a statement is"
      extraction_hints:
        - "Contains specific numbers or dates"
        - "Attributes to named source"
        - "Makes testable prediction"
        - "Uses hedging language (may, might, could)"

    url_suspicion:
      description: "Phishing/fraud indicators in URLs"
      extraction_hints:
        - "Punycode characters"
        - "Homoglyph substitutions"
        - "Unusual TLD patterns"
        - "Excessive subdomains"
        - "IP address instead of domain"

    data_sensitivity:
      description: "PII and sensitive data indicators"
      extraction_hints:
        - "Email patterns"
        - "Phone number formats"
        - "Address structures"
        - "ID number patterns"
        - "Financial data markers"

    code_quality:
      description: "Code/config health indicators"
      extraction_hints:
        - "Version range patterns"
        - "Dependency duplicates"
        - "Known problematic packages"
        - "Configuration anti-patterns"

    statistical_validity:
      description: "Statistical rigor indicators"
      extraction_hints:
        - "Sample size adequacy"
        - "Assumption satisfaction"
        - "Effect size reporting"
        - "Multiple testing consideration"

    workflow_coherence:
      description: "Workflow quality indicators"
      extraction_hints:
        - "Input/output type matching"
        - "Logical step ordering"
        - "Resource efficiency"
        - "Error handling coverage"

  # ---------------------------------------------------------------------------
  # Measures - Quality constraints that outputs must satisfy
  # ---------------------------------------------------------------------------
  measures:
    working_implementation:
      constraints:
        - "execute() function contains real logic, not placeholder comments"
        - "No TODO, FIXME, or 'Not implemented' in output"
        - "Returns actual computed values, not hardcoded test data"
      severity: error

    valid_output_structure:
      constraints:
        - "Returns object matching declared interface"
        - "All required fields are present and typed correctly"
        - "Arrays are never undefined, use empty array []"
        - "Null/undefined distinction is intentional and documented"
      severity: error

    proper_error_handling:
      constraints:
        - "Throws descriptive Error with context on failure"
        - "Validates inputs before processing"
        - "Catches and wraps external API errors"
        - "Network errors include URL and status information"
      severity: error

    ai_sdk_compliance:
      constraints:
        - "Uses tool() from 'ai' package"
        - "Uses jsonSchema() for input schema (not Zod directly)"
        - "Description is clear and actionable for LLMs"
        - "Input schema has descriptions for each property"
      severity: error

    npm_publishable:
      constraints:
        - "Has valid package.json with tpmjs field"
        - "Exports tool as both named and default export"
        - "Has proper TypeScript types exported"
        - "Version follows semver"
      severity: error

    readme_documentation:
      constraints:
        - "README.md exists in the package root"
        - "README describes what the tool does"
        - "README includes usage example with code snippet"
        - "README documents all input parameters"
        - "README documents the output structure"
        - "README matches the actual implementation behavior"
      severity: error

    deterministic_output:
      constraints:
        - "Same input produces same output (where applicable)"
        - "Random elements are seeded or documented"
        - "Timestamps use provided values or are clearly marked"
      severity: warning

    minimal_dependencies:
      constraints:
        - "Only includes necessary runtime dependencies"
        - "Prefers well-maintained, stable packages"
        - "Avoids packages with known vulnerabilities"
      severity: warning

# =============================================================================
# DOMAIN RULES - Enforce code quality across all blocks (documentation only)
# =============================================================================
domain_rules:
    # -------------------------------------------------------------------------
    # Core implementation rules (apply to ALL tools)
    # -------------------------------------------------------------------------
    - id: no_stub_implementations
      description: |
        CRITICAL: Tools must be fully implemented with real functionality.
        - No TODO comments in execute()
        - No placeholder returns like "Not implemented"
        - No hardcoded test data as output
        - The tool must actually perform the described operation

    - id: ai_sdk_v6_pattern
      description: |
        All tools MUST use the AI SDK v6 pattern:
        - import { tool, jsonSchema } from 'ai'
        - Use tool() wrapper with description and inputSchema
        - Use jsonSchema<T>() for type-safe input schema
        - Include 'additionalProperties: false' in JSON schema
        - Make execute() async and properly typed

    - id: proper_json_schema
      description: |
        Input schemas must be complete and LLM-friendly:
        - Every property needs a 'description' field
        - Use 'required' array to specify mandatory fields
        - Include 'additionalProperties: false'
        - Use correct JSON Schema types (string, number, boolean, array, object)
        - For enums, use 'enum' with array of allowed values

    - id: structured_outputs
      description: |
        Tools must return well-structured, typed objects:
        - Define TypeScript interface for output type
        - Export interface so consumers can use it
        - All fields should have meaningful names
        - Use arrays for collections, never undefined
        - Include metadata fields where helpful (timestamp, source, confidence)

    - id: input_validation
      description: |
        Validate inputs at the start of execute():
        - Check required fields are present and non-empty
        - Validate URLs are well-formed when accepting URLs
        - Validate numbers are in expected ranges
        - Throw descriptive errors for invalid input
        - Don't silently accept bad data

    - id: async_error_handling
      description: |
        Handle async operations properly:
        - Wrap fetch/network calls in try-catch
        - Provide meaningful error messages with context
        - Don't let errors silently fail to empty output
        - Include original error in wrapped errors
        - Set reasonable timeouts for network operations

    - id: readme_code_alignment
      description: |
        README.md must accurately reflect the implementation:
        - Tool description in README matches tool() description in code
        - Input parameters documented in README match jsonSchema properties
        - Output structure in README matches TypeScript interface
        - Usage examples in README are valid and would actually work
        - Any limitations or requirements mentioned are accurate
        - No outdated information from previous versions

    # -------------------------------------------------------------------------
    # Web & fetch rules (apply to web.* and research.* tools)
    # -------------------------------------------------------------------------
    - id: safe_fetch_patterns
      description: |
        All network fetching must be safe and robust:
        - Set timeout (default 30s max)
        - Set max bytes limit to prevent memory issues
        - Handle redirects explicitly (manual mode when tracing)
        - Include User-Agent header
        - Handle charset/encoding properly
        - Verify Node.js 18+ fetch availability

    - id: html_parsing_standards
      description: |
        HTML parsing must be consistent and safe:
        - Use jsdom or cheerio for DOM parsing
        - Handle malformed HTML gracefully
        - Extract text content without script/style
        - Preserve semantic structure where needed
        - Handle missing elements without crashing

    - id: url_handling
      description: |
        URL operations must be correct:
        - Use URL constructor for parsing
        - Resolve relative URLs against base
        - Normalize for comparison/dedupe
        - Handle edge cases (trailing slashes, default ports)
        - Validate URL format before fetching

    # -------------------------------------------------------------------------
    # Document generation rules (apply to doc.* tools)
    # -------------------------------------------------------------------------
    - id: template_based_generation
      description: |
        Document tools should use structured templates:
        - Define clear section structure
        - Use consistent heading hierarchy
        - Include placeholder guidance in optional sections
        - Support customization through parameters
        - Output valid markdown

    - id: content_extraction_patterns
      description: |
        When extracting from text:
        - Use sentence boundary detection (sbd) for splitting
        - Preserve context around extracted items
        - Handle edge cases (abbreviations, numbers)
        - Return source references where applicable

    - id: audience_aware_output
      description: |
        Generated documents should consider audience:
        - Technical vs non-technical language
        - Appropriate level of detail
        - Actionable recommendations
        - Clear structure for scanning

    # -------------------------------------------------------------------------
    # Data transformation rules (apply to data.* tools)
    # -------------------------------------------------------------------------
    - id: format_parsing_robustness
      description: |
        Data format parsing must be robust:
        - Handle common format variations
        - Provide meaningful parse errors
        - Support lenient mode where appropriate
        - Preserve data types correctly
        - Handle empty/null values consistently

    - id: type_inference_patterns
      description: |
        Type inference should be predictable:
        - Infer number, boolean, date from string patterns
        - Document inference rules
        - Allow override/explicit typing
        - Handle mixed-type columns gracefully

    - id: row_operation_standards
      description: |
        Row operations must be consistent:
        - Use stable sort algorithms
        - Handle null/undefined in comparisons
        - Support multiple sort keys
        - Preserve row identity through transforms
        - Return new arrays, don't mutate input

    # -------------------------------------------------------------------------
    # Engineering tool rules (apply to eng.* tools)
    # -------------------------------------------------------------------------
    - id: code_analysis_patterns
      description: |
        Code/config analysis should be helpful:
        - Identify patterns, not just syntax
        - Provide actionable suggestions
        - Include severity levels
        - Reference best practices
        - Avoid false positives

    - id: diff_and_comparison
      description: |
        Diff operations must be clear:
        - Use unified diff format
        - Show context lines
        - Handle large files gracefully
        - Identify semantic vs whitespace changes

    - id: schema_validation_standards
      description: |
        Schema validation must be thorough:
        - Use established validators (ajv)
        - Return all errors, not just first
        - Include path to error location
        - Suggest fixes where possible

    # -------------------------------------------------------------------------
    # Security tool rules (apply to sec.* and compliance.* tools)
    # -------------------------------------------------------------------------
    - id: security_heuristics
      description: |
        Security analysis must be practical:
        - Use established patterns (OWASP, etc.)
        - Minimize false positives
        - Prioritize by severity
        - Provide remediation guidance
        - Never store or log actual secrets

    - id: secret_detection_patterns
      description: |
        Secret detection must be comprehensive:
        - Cover common secret patterns (API keys, tokens, passwords)
        - Use curated regex patterns
        - Minimize false positives on UUIDs, hashes
        - Include confidence levels
        - Support custom patterns

    - id: redaction_safety
      description: |
        Redaction must be thorough:
        - Replace entire secret, not partial
        - Keep consistent redaction markers
        - Optionally preserve format hints
        - Log redaction fingerprints for audit
        - Handle overlapping patterns

    # -------------------------------------------------------------------------
    # Statistics tool rules (apply to stats.* tools)
    # -------------------------------------------------------------------------
    - id: statistical_rigor
      description: |
        Statistical tools must be methodologically sound:
        - Document assumptions required
        - Check assumptions where possible
        - Report appropriate precision
        - Use established implementations
        - Include effect sizes, not just p-values

    - id: numerical_stability
      description: |
        Numerical computations must be stable:
        - Use appropriate algorithms for scale
        - Handle edge cases (empty, single value)
        - Avoid floating point issues
        - Document numerical limitations

    - id: resampling_methods
      description: |
        Resampling methods must be correct:
        - Use sufficient iterations (1000+ for bootstrap)
        - Support seeding for reproducibility
        - Report method used
        - Handle small sample sizes appropriately

    # -------------------------------------------------------------------------
    # Agent/workflow tool rules (apply to agent.* tools)
    # -------------------------------------------------------------------------
    - id: workflow_structure
      description: |
        Workflow specifications must be valid:
        - Use consistent step structure
        - Validate input/output type chains
        - Include error handling steps
        - Support conditional branches
        - Be serializable to JSON

    - id: recipe_generation
      description: |
        Generated recipes must be coherent:
        - Follow grammar/template constraints
        - Produce executable workflows
        - Avoid redundant steps
        - Consider resource constraints
        - Support variation meaningfully

    - id: evaluation_patterns
      description: |
        Evaluation tools must be fair:
        - Use consistent scoring methods
        - Support partial credit where appropriate
        - Handle missing/extra items
        - Report confidence in scores

# ===========================================================================
# BLOCK DEFINITIONS - All 100 tools organized by category
# ===========================================================================
blocks:
  # ---------------------------------------------------------------------------
  # A) Web Research & Evidence (15 tools)
  # ---------------------------------------------------------------------------
  research.pageBrief:
    type: utility
    description: "Fetches a URL, extracts main content using Readability algorithm, and returns a structured brief with summary, key points, and claims that need citations"
    path: "page-brief"
    domain_rules:
      - id: url_fetching
        description: "Must actually fetch the URL using fetch() API with timeout"
      - id: content_extraction
        description: "Must use @mozilla/readability for content extraction"
      - id: sentence_parsing
        description: "Must parse text into sentences for claim extraction using sbd"
    inputs:
      - name: url
        type: string
        description: "The URL to fetch and analyze"
    outputs:
      - name: brief
        type: PageBrief
        description: "Structured summary with key points and claims needing citation"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  research.comparePages:
    type: utility
    description: "Compares content from two URLs, identifying agreements, conflicts, and unique points from each source using TF-IDF similarity"
    path: "compare-pages"
    domain_rules:
      - id: dual_fetch
        description: "Must fetch both URLs and handle failures gracefully"
      - id: content_comparison
        description: "Must perform actual text comparison using TF-IDF (natural library)"
      - id: structured_diff
        description: "Must categorize differences into agreements/conflicts/unique"
    inputs:
      - name: urlA
        type: string
        description: "First URL to compare"
      - name: urlB
        type: string
        description: "Second URL to compare"
    outputs:
      - name: comparison
        type: PageComparison
        description: "Structured comparison showing agreements, conflicts, and unique content"
        measures: [working_implementation, valid_output_structure, proper_error_handling, readme_documentation]

  research.sourceCredibility:
    type: utility
    description: "Analyzes a URL for credibility signals using heuristics like HTTPS, domain reputation, author presence, publication date, and citation density"
    path: "source-credibility"
    domain_rules:
      - id: credibility_heuristics
        description: |
          Must check real credibility signals:
          - HTTPS vs HTTP protocol
          - Domain TLD and reputation (.edu, .gov, .org vs others)
          - Author byline presence
          - Publication date presence
          - External citations/references
          - Contact information
      - id: score_calculation
        description: "Score must be computed from actual signals, not random/hardcoded"
    inputs:
      - name: url
        type: string
        description: "The URL to analyze for credibility"
      - name: html
        type: string
        optional: true
        description: "Pre-fetched HTML content (if available)"
    outputs:
      - name: credibility
        type: CredibilityScore
        description: "Credibility assessment with score, factors, and recommendations"
        measures: [working_implementation, valid_output_structure, proper_error_handling, readme_documentation]

  research.claimChecklist:
    type: utility
    description: "Extracts factual claims from text and identifies which ones need citations, categorizing by type and priority"
    path: "claim-checklist"
    domain_rules:
      - id: claim_extraction
        description: |
          Must identify claims using real heuristics:
          - Statements with numbers/statistics
          - Quotes attributed to people
          - Statements about events/facts
          - Predictions or projections
      - id: citation_detection
        description: "Must check if claims are supported by inline citations"
      - id: priority_assignment
        description: "Must assign priority based on claim type and verifiability"
    inputs:
      - name: text
        type: string
        description: "The text to analyze for claims"
    outputs:
      - name: checklist
        type: ClaimChecklist
        description: "List of claims with citation status and priority ranking"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  research.timelineFromText:
    type: utility
    description: "Extracts dated events from unstructured text and returns a normalized, chronologically sorted timeline with confidence scores"
    path: "timeline-from-text"
    domain_rules:
      - id: date_extraction
        description: |
          Must parse dates in multiple formats using chrono-node:
          - Full dates (January 1, 2024)
          - Partial dates (March 2024, Q1 2024)
          - Relative dates (last year, in 2020)
          - Ranges (2020-2024)
      - id: event_association
        description: "Must associate extracted dates with their context/events"
      - id: chronological_sorting
        description: "Output events must be sorted chronologically"
    inputs:
      - name: text
        type: string
        description: "The text to extract timeline from"
    outputs:
      - name: timeline
        type: Timeline
        description: "Chronologically sorted events with dates and confidence scores"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  research.rssRead:
    type: utility
    description: "Parses RSS/Atom feeds and returns normalized items with title, link, date, and summary"
    path: "rss-read"
    domain_rules:
      - id: feed_parsing
        description: "Must use rss-parser for robust RSS/Atom parsing"
      - id: item_normalization
        description: "Must normalize items to consistent structure regardless of feed type"
      - id: date_handling
        description: "Must parse various date formats to ISO strings"
    inputs:
      - name: url
        type: string
        description: "The RSS or Atom feed URL to parse (must be http or https)"
      - name: limit
        type: number
        optional: true
        description: "Maximum number of items to return (default: 20, max: 100)"
    outputs:
      - name: feed
        type: RssFeedMetadata
        description: "Feed metadata (title, link, description, language)"
      - name: items
        type: RssFeedItem[]
        description: "Array of feed items with title, link, description, pubDate, author"
      - name: itemCount
        type: number
        description: "Number of items returned"
      - name: metadata
        type: FeedMetadata
        description: "Fetch metadata (fetchedAt, feedType, totalItems, limitApplied)"
        measures: [working_implementation, valid_output_structure, proper_error_handling, readme_documentation]

  research.sitemapRead:
    type: utility
    description: "Parses sitemap XML including sitemap indexes and returns URLs for crawling/indexing"
    path: "sitemap-read"
    domain_rules:
      - id: xml_parsing
        description: "Must use fast-xml-parser for XML parsing"
      - id: index_handling
        description: "Must detect and handle sitemap index files"
      - id: url_extraction
        description: "Must extract URLs with lastmod and priority if available"
    inputs:
      - name: sitemapUrl
        type: string
        description: "The sitemap URL to parse"
    outputs:
      - name: sitemap
        type: Sitemap
        description: "Parsed sitemap with URLs and metadata"
        measures: [working_implementation, valid_output_structure, proper_error_handling, readme_documentation]

  research.robotsPolicy:
    type: utility
    description: "Fetches and parses robots.txt and checks if URLs are allowed for crawling"
    path: "robots-policy"
    domain_rules:
      - id: robots_parsing
        description: "Must parse robots.txt according to standard format"
      - id: rule_extraction
        description: "Must extract allow, disallow, crawl-delay, and sitemap rules"
      - id: user_agent_matching
        description: "Must support querying rules for specific user agents"
    inputs:
      - name: robotsUrl
        type: string
        description: "URL to the robots.txt file to fetch and parse"
      - name: testUrl
        type: string
        description: "URL to check if allowed or disallowed"
      - name: userAgent
        type: string
        optional: true
        description: "User agent to check rules for (default: *)"
    outputs:
      - name: policy
        type: RobotsPolicy
        description: "Structured robots.txt rules with allow/disallow result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, readme_documentation]

  web.fetchText:
    type: utility
    description: "Safe fetch wrapper with max bytes, timeout, redirects policy, and charset decoding"
    path: "fetch-text"
    domain_rules:
      - id: safe_fetch
        description: |
          Must implement safe fetch patterns:
          - Configurable timeout (default 30s)
          - Max bytes limit
          - Redirect policy (follow/manual)
          - Charset detection and decoding
      - id: error_handling
        description: "Must wrap network errors with context"
    inputs:
      - name: url
        type: string
        description: "The URL to fetch"
      - name: maxBytes
        type: number
        optional: true
        description: "Maximum bytes to read (default 5MB)"
      - name: timeoutMs
        type: number
        optional: true
        description: "Timeout in milliseconds (default 30000)"
    outputs:
      - name: result
        type: FetchResult
        description: "Fetched text with metadata"
        measures: [working_implementation, valid_output_structure, proper_error_handling, readme_documentation]

  web.redirectTrace:
    type: utility
    description: "Returns full redirect chain for URL canonicalization and diagnosing paywall/geo redirects"
    path: "redirect-trace"
    domain_rules:
      - id: manual_redirects
        description: "Must use fetch with redirect:'manual' to trace each hop"
      - id: chain_building
        description: "Must build complete chain with status codes and locations"
      - id: loop_detection
        description: "Must detect and break redirect loops"
    inputs:
      - name: url
        type: string
        description: "The URL to trace"
      - name: maxHops
        type: number
        optional: true
        description: "Maximum redirects to follow (default 10)"
    outputs:
      - name: trace
        type: RedirectTrace
        description: "Full redirect chain with final destination"
        measures: [working_implementation, valid_output_structure, proper_error_handling, readme_documentation]

  web.extractMeta:
    type: utility
    description: "Extracts title, description, canonical, OG, and Twitter tags for previews and indexing"
    path: "extract-meta"
    domain_rules:
      - id: meta_extraction
        description: "Must use cheerio to extract all standard meta tags"
      - id: og_parsing
        description: "Must parse Open Graph tags completely"
      - id: twitter_parsing
        description: "Must parse Twitter Card tags"
    inputs:
      - name: url
        type: string
        description: "The URL to extract meta tags from (must be http or https)"
    outputs:
      - name: title
        type: string
        description: "Page title"
      - name: description
        type: string
        description: "Meta description"
      - name: canonical
        type: string
        description: "Canonical URL"
      - name: ogTags
        type: object
        description: "Open Graph tags as key-value pairs"
      - name: twitterTags
        type: object
        description: "Twitter Card tags as key-value pairs"
      - name: metadata
        type: FetchMetadata
        description: "Fetch metadata (url, fetchedAt, contentType, hasOpenGraph, hasTwitterCard)"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  web.extractJsonLd:
    type: utility
    description: "Extracts JSON-LD blocks, parses leniently, and returns schema objects for articles/products/events"
    path: "extract-json-ld"
    domain_rules:
      - id: jsonld_extraction
        description: "Must find all script[type='application/ld+json'] blocks"
      - id: lenient_parsing
        description: "Must use lenient JSON parser for malformed JSON-LD"
      - id: schema_typing
        description: "Must identify schema.org types"
    inputs:
      - name: url
        type: string
        description: "The URL to fetch and extract JSON-LD from"
    outputs:
      - name: jsonLd
        type: JsonLdExtraction
        description: "Extracted and parsed JSON-LD objects with types and metadata"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  web.linksCatalog:
    type: utility
    description: "Extracts links and classifies internal/external with resolved URLs and anchor text"
    path: "links-catalog"
    domain_rules:
      - id: link_extraction
        description: "Must extract all anchor tags with href"
      - id: classification
        description: "Must classify as internal or external based on domain"
      - id: url_resolution
        description: "Must resolve relative URLs against base"
    inputs:
      - name: html
        type: string
        description: "The HTML content to parse"
      - name: baseUrl
        type: string
        description: "The base URL for resolution and classification"
    outputs:
      - name: links
        type: LinksCatalog
        description: "Categorized links with resolved URLs"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  web.tableExtract:
    type: utility
    description: "Pulls HTML tables into normalized headers and rows arrays"
    path: "table-extract"
    domain_rules:
      - id: table_parsing
        description: "Must use cheerio to parse table elements"
      - id: header_detection
        description: "Must detect headers from th or first row"
      - id: cell_normalization
        description: "Must normalize cell content (trim, collapse whitespace)"
    inputs:
      - name: url
        type: string
        description: "The URL to fetch and extract tables from"
      - name: tableIndex
        type: number
        optional: true
        description: "Optional 0-based index to extract specific table"
    outputs:
      - name: tables
        type: TableExtraction
        description: "Extracted tables with headers, rows, and metadata"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # B) Writing, Docs & Deliverables (15 tools)
  # ---------------------------------------------------------------------------
  doc.executiveBrief:
    type: utility
    description: "Produces a 1-page executive brief with 'what happened / so what / recommendation' structure"
    path: "executive-brief"
    domain_rules:
      - id: structure
        description: "Must follow What/So What/Recommendation format"
      - id: audience_adaptation
        description: "Must adapt language for specified audience"
      - id: actionable_output
        description: "Must include clear, actionable recommendations"
    inputs:
      - name: content
        type: string
        description: "The content to format into an executive brief"
      - name: maxBullets
        type: number
        optional: true
        description: "Maximum number of bullet points to include (default: 5)"
    outputs:
      - name: brief
        type: string
        description: "Formatted executive brief in markdown"
      - name: bulletCount
        type: number
        description: "Number of bullet points included"
      - name: wordCount
        type: number
        description: "Word count of the brief"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.runbookDraft:
    type: utility
    description: "Converts a procedure into an operational runbook with prechecks, steps, rollback, and verify sections"
    path: "runbook-draft"
    domain_rules:
      - id: runbook_structure
        description: "Must include prechecks, steps, rollback, and verify sections"
      - id: step_formatting
        description: "Steps must be numbered and actionable"
      - id: safety_checks
        description: "Must include safety prechecks and rollback procedures"
    inputs:
      - name: title
        type: string
        description: "Title of the runbook"
      - name: steps
        type: RunbookStep[]
        description: "Array of procedure steps with action, optional command, and optional verification"
      - name: prechecks
        type: PrecheckItem[]
        optional: true
        description: "Optional prechecks to run before starting the procedure"
      - name: rollback
        type: RollbackStep[]
        optional: true
        description: "Optional rollback steps to revert changes if something goes wrong"
    outputs:
      - name: runbook
        type: string
        description: "Formatted runbook in markdown with prechecks, procedure, verification, and rollback sections"
      - name: stepCount
        type: number
        description: "Number of steps in the runbook"
      - name: hasCommands
        type: boolean
        description: "Whether any steps include commands"
      - name: hasPrechecks
        type: boolean
        description: "Whether the runbook includes prechecks"
      - name: hasRollback
        type: boolean
        description: "Whether the runbook includes rollback steps"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.postmortemDraft:
    type: utility
    description: "Generates postmortem skeleton with timeline, impact, root cause hypotheses, and actions"
    path: "postmortem-draft"
    domain_rules:
      - id: postmortem_structure
        description: "Must include timeline, impact, root cause, and actions"
      - id: timeline_extraction
        description: "Must extract timeline from notes/logs if provided"
      - id: blameless_framing
        description: "Must use blameless language focusing on systems"
    inputs:
      - name: title
        type: string
        description: "Title of the incident"
      - name: timeline
        type: TimelineEvent[]
        description: "Array of timeline events with time and event description"
      - name: rootCause
        type: string
        description: "Root cause analysis of the incident"
      - name: actionItems
        type: string[]
        description: "Array of action items to prevent recurrence"
    outputs:
      - name: postmortem
        type: string
        description: "Formatted postmortem document in markdown"
      - name: severity
        type: string
        description: "Assessed severity (low, medium, high, critical)"
      - name: duration
        type: string
        description: "Calculated incident duration"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.faqFromText:
    type: utility
    description: "Builds a FAQ with Q/A pairs from a reference document, with automatic categorization"
    path: "faq-from-text"
    domain_rules:
      - id: question_generation
        description: "Must identify likely questions from content"
      - id: answer_extraction
        description: "Must extract concise answers"
      - id: organization
        description: "Must organize by topic/category"
    inputs:
      - name: text
        type: string
        description: "Text containing FAQ-style content with questions and answers"
    outputs:
      - name: faqs
        type: FaqItem[]
        description: "Array of extracted question-answer pairs with category"
      - name: categories
        type: CategoryGroup[]
        description: "FAQs grouped by category with counts"
      - name: count
        type: number
        description: "Number of FAQ items extracted"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.glossaryBuild:
    type: utility
    description: "Extracts domain terms and concise definitions from corpus context with malformed input handling"
    path: "glossary-build"
    domain_rules:
      - id: term_extraction
        description: "Must identify domain-specific terms"
      - id: definition_generation
        description: "Must generate concise definitions from context"
      - id: deduplication
        description: "Must dedupe terms and merge definitions"
      - id: malformed_input
        description: "Must gracefully handle malformed input with warnings"
    inputs:
      - name: text
        type: string
        description: "Text containing term definitions in various formats"
    outputs:
      - name: terms
        type: GlossaryTerm[]
        description: "Array of extracted term-definition pairs"
      - name: count
        type: number
        description: "Number of terms extracted"
      - name: alphabetized
        type: boolean
        description: "Whether terms are alphabetically sorted"
      - name: warnings
        type: GlossaryWarning[]
        description: "Warnings for potentially malformed input"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.tocGenerate:
    type: utility
    description: "Generates a Markdown table of contents from headings"
    path: "toc-generate"
    domain_rules:
      - id: heading_extraction
        description: "Must parse markdown headings correctly"
      - id: anchor_generation
        description: "Must generate valid anchor links"
      - id: depth_control
        description: "Must respect maxDepth parameter"
    inputs:
      - name: markdown
        type: string
        description: "The markdown content to generate table of contents from"
      - name: maxDepth
        type: number
        optional: true
        description: "Maximum heading depth to include (1-6, default: 3)"
    outputs:
      - name: toc
        type: string
        description: "Formatted table of contents in markdown"
      - name: headings
        type: Heading[]
        description: "Array of parsed headings with level, text, slug, and line"
      - name: depth
        type: DepthInfo
        description: "Depth statistics (min, max, included count)"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.markdownLintBasic:
    type: utility
    description: "Flags broken heading order, empty links, trailing spaces, and other markdown issues"
    path: "markdown-lint-basic"
    domain_rules:
      - id: lint_rules
        description: "Must check common markdown issues"
      - id: issue_reporting
        description: "Must report line numbers and descriptions"
      - id: severity_levels
        description: "Must indicate error vs warning severity"
    inputs:
      - name: markdown
        type: string
        description: "The markdown document to lint"
    outputs:
      - name: issues
        type: LintResult
        description: "List of issues found"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.styleRewrite:
    type: utility
    description: "Rewrites text to a specified tone without changing meaning"
    path: "style-rewrite"
    domain_rules:
      - id: tone_adaptation
        description: "Must adapt to specified tone (formal/terse/friendly)"
      - id: meaning_preservation
        description: "Must preserve core meaning and facts"
      - id: format_preservation
        description: "Must preserve structure and formatting"
    inputs:
      - name: text
        type: string
        description: "The text to rewrite"
      - name: targetTone
        type: string
        description: "Target tone (formal, terse, friendly, technical)"
    outputs:
      - name: rewritten
        type: StyleRewriteResult
        description: "Rewritten text with change notes"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.meetingMinutesFormat:
    type: utility
    description: "Turns messy notes into minutes with decisions and action items"
    path: "meeting-minutes-format"
    domain_rules:
      - id: structure_extraction
        description: "Must identify decisions, action items, and key points"
      - id: cue_phrase_detection
        description: "Must detect phrases like 'decided', 'action', 'owner'"
      - id: formatting
        description: "Must output clean, structured minutes"
    inputs:
      - name: notes
        type: string
        description: "Raw meeting notes"
    outputs:
      - name: minutes
        type: MeetingMinutes
        description: "Formatted meeting minutes"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.decisionRecordADR:
    type: utility
    description: "Produces an Architecture Decision Record with context, decision, alternatives, and consequences"
    path: "decision-record-adr"
    domain_rules:
      - id: adr_structure
        description: "Must follow standard ADR format"
      - id: alternatives_analysis
        description: "Must include considered alternatives"
      - id: consequences_section
        description: "Must document consequences of decision"
    inputs:
      - name: title
        type: string
        description: "Title of the decision (e.g., 'Use PostgreSQL for primary database')"
      - name: context
        type: string
        description: "Context and background information that led to this decision"
      - name: decision
        type: string
        description: "The decision that was made"
      - name: consequences
        type: string[]
        description: "Array of consequences (both positive and negative)"
    outputs:
      - name: adr
        type: string
        description: "Formatted ADR document in markdown"
      - name: date
        type: string
        description: "Date the ADR was created"
      - name: status
        type: string
        description: "Status of the decision (Accepted)"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.changelogEntry:
    type: utility
    description: "Groups change notes into Added/Changed/Fixed/Removed entries"
    path: "changelog-entry"
    domain_rules:
      - id: classification
        description: "Must classify changes by type (added/changed/fixed/removed)"
      - id: conventional_commits
        description: "Should parse conventional commit format if present"
      - id: keepachangelog_format
        description: "Must output in Keep a Changelog format"
    inputs:
      - name: version
        type: string
        description: "Version number (e.g., '1.2.0', 'v1.2.0', or 'Unreleased')"
      - name: changes
        type: Change[]
        description: "Array of changes with type (Added/Changed/Fixed/etc) and description"
      - name: date
        type: string
        optional: true
        description: "Optional date for the release (YYYY-MM-DD), defaults to today"
    outputs:
      - name: entry
        type: string
        description: "Formatted changelog entry in markdown"
      - name: date
        type: string
        description: "Formatted date string"
      - name: types
        type: string[]
        description: "Array of change types used"
      - name: version
        type: string
        description: "Normalized version string"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.releaseNotes:
    type: utility
    description: "Converts technical changes into user-facing release notes"
    path: "release-notes"
    domain_rules:
      - id: audience_adaptation
        description: "Must convert technical to user-friendly language"
      - id: highlights_extraction
        description: "Must identify key highlights"
      - id: breaking_changes
        description: "Must prominently note breaking changes"
    inputs:
      - name: version
        type: string
        description: "Version number (e.g., '1.2.0', 'v2.0.0-beta.1')"
      - name: changes
        type: ReleaseChange[]
        description: "Array of changes with type (feature/fix/breaking/etc), description, and optional issue"
    outputs:
      - name: notes
        type: string
        description: "Formatted release notes in markdown"
      - name: version
        type: string
        description: "Version string"
      - name: date
        type: string
        description: "Release date"
      - name: summary
        type: ReleaseSummary
        description: "Summary with counts by type (features, fixes, breaking, other)"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.prdOutline:
    type: utility
    description: "Generates PRD structure with problem, goals, non-goals, UX, metrics, risks, and rollout"
    path: "prd-outline"
    domain_rules:
      - id: prd_structure
        description: "Must include all standard PRD sections"
      - id: placeholder_guidance
        description: "Must include guidance for filling each section"
      - id: metrics_suggestions
        description: "Must suggest success metrics"
    inputs:
      - name: title
        type: string
        description: "Title of the product or feature"
      - name: problem
        type: string
        description: "Problem statement describing what needs to be solved"
      - name: goals
        type: string[]
        description: "Array of goals for the product or feature"
      - name: features
        type: string[]
        description: "Array of features to include"
    outputs:
      - name: prd
        type: string
        description: "Formatted PRD document in markdown"
      - name: sections
        type: string[]
        description: "List of sections included in the PRD"
      - name: featureCount
        type: number
        description: "Number of features included"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.acceptanceCriteria:
    type: utility
    description: "Turns feature description into testable acceptance criteria in Given-When-Then format"
    path: "acceptance-criteria"
    domain_rules:
      - id: gwt_format
        description: "Must use Given-When-Then format"
      - id: testability
        description: "Criteria must be testable and specific"
      - id: coverage
        description: "Must cover happy path and edge cases"
    inputs:
      - name: story
        type: string
        description: "The user story or feature description"
      - name: criteria
        type: Criterion[]
        description: "Array of criteria with given, when, then properties in Gherkin format"
    outputs:
      - name: formatted
        type: string
        description: "Formatted acceptance criteria in markdown"
      - name: criteriaCount
        type: number
        description: "Number of criteria included"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  doc.testPlanMatrix:
    type: utility
    description: "Produces a QA test matrix with scenarios, steps, expected results, and priority"
    path: "test-plan-matrix"
    domain_rules:
      - id: scenario_generation
        description: "Must generate test scenarios from requirements"
      - id: step_detail
        description: "Must include detailed test steps"
      - id: priority_assignment
        description: "Must assign priority levels"
    inputs:
      - name: features
        type: string[]
        description: "List of features to test"
      - name: testTypes
        type: string[]
        description: "List of test types (e.g., unit, integration, e2e, performance)"
      - name: coverage
        type: object
        optional: true
        description: "Optional coverage mapping. Keys are feature names, values are arrays of test types."
    outputs:
      - name: matrix
        type: MatrixCell[][]
        description: "2D matrix showing coverage of each feature by each test type"
      - name: coverage
        type: CoverageStats[]
        description: "Coverage statistics for each feature"
      - name: gaps
        type: CoverageGap[]
        description: "Identified gaps where features lack certain test types"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # C) Data Wrangling & Transforms (15 tools)
  # ---------------------------------------------------------------------------
  data.csvParse:
    type: utility
    description: "Parses CSV into headers and rows with light type inference"
    path: "csv-parse"
    domain_rules:
      - id: csv_parsing
        description: "Must use papaparse for robust CSV parsing"
      - id: type_inference
        description: "Must infer number and boolean types"
      - id: error_handling
        description: "Must handle malformed rows gracefully"
    inputs:
      - name: csv
        type: string
        description: "CSV content to parse"
      - name: delimiter
        type: string
        optional: true
        description: "Field delimiter (default: auto-detect)"
    outputs:
      - name: data
        type: CsvData
        description: "Parsed CSV with headers and typed rows"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.csvStringify:
    type: utility
    description: "Converts rows back to CSV with stable column ordering"
    path: "csv-stringify"
    domain_rules:
      - id: csv_generation
        description: "Must use papaparse for CSV generation"
      - id: column_ordering
        description: "Must maintain stable column order"
      - id: escaping
        description: "Must properly escape special characters"
    inputs:
      - name: rows
        type: object[]
        description: "Array of row objects"
      - name: columns
        type: string[]
        optional: true
        description: "Column order (default: from first row)"
    outputs:
      - name: csv
        type: string
        description: "Generated CSV string"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.yamlParse:
    type: utility
    description: "Parses YAML safely into JSON"
    path: "yaml-parse"
    domain_rules:
      - id: yaml_parsing
        description: "Must use yaml library for safe parsing"
      - id: security
        description: "Must not execute code in YAML"
      - id: error_messages
        description: "Must provide helpful parse error messages"
    inputs:
      - name: yaml
        type: string
        description: "YAML content to parse"
    outputs:
      - name: data
        type: object
        description: "Parsed JSON object"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.yamlStringify:
    type: utility
    description: "Converts JavaScript data to YAML with formatting options"
    path: "yaml-stringify"
    domain_rules:
      - id: yaml_generation
        description: "Must use yaml library for generation"
      - id: formatting
        description: "Must support indentation options"
    inputs:
      - name: data
        type: any
        description: "JavaScript data to convert to YAML"
      - name: indent
        type: number
        optional: true
        description: "Indentation spaces (default: 2, range: 1-8)"
    outputs:
      - name: yaml
        type: YamlStringifyResult
        description: "Generated YAML string with metadata"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.jsonRepair:
    type: utility
    description: "Repairs common JSON formatting errors and parses the result"
    path: "json-repair"
    domain_rules:
      - id: repair_logic
        description: "Must use jsonrepair library"
      - id: common_errors
        description: "Must handle trailing commas, unquoted keys, single quotes"
      - id: reporting
        description: "Must report what was repaired"
    inputs:
      - name: text
        type: string
        description: "Malformed JSON text"
    outputs:
      - name: result
        type: JsonRepairResult
        description: "Repaired and parsed JSON"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.jsonSchemaValidate:
    type: utility
    description: "Validates JSON against a JSON Schema and returns detailed errors"
    path: "json-schema-validate"
    domain_rules:
      - id: validation
        description: "Must use ajv for validation"
      - id: error_detail
        description: "Must return all errors with paths"
      - id: formats
        description: "Must support common formats (email, uri, date-time)"
    inputs:
      - name: data
        type: object
        description: "Data to validate"
      - name: schema
        type: object
        description: "JSON Schema to validate against"
    outputs:
      - name: result
        type: ValidationResult
        description: "Validation result with errors"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.rowsFilter:
    type: utility
    description: "Filters rows using a predicate DSL (field/operator/value)"
    path: "rows-filter"
    domain_rules:
      - id: predicate_parsing
        description: "Must support operators: eq, ne, gt, lt, gte, lte, contains, startsWith"
      - id: type_handling
        description: "Must handle type coercion correctly"
      - id: null_handling
        description: "Must handle null/undefined fields"
    inputs:
      - name: rows
        type: object[]
        description: "Array of row objects"
      - name: where
        type: object
        description: "Filter predicate {field, op, value}"
    outputs:
      - name: filtered
        type: object[]
        description: "Filtered rows"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.rowsSort:
    type: utility
    description: "Stable multi-key sort with null handling"
    path: "rows-sort"
    domain_rules:
      - id: stable_sort
        description: "Must use stable sort algorithm"
      - id: multi_key
        description: "Must support multiple sort keys with direction"
      - id: null_handling
        description: "Must handle nulls consistently (first or last)"
    inputs:
      - name: rows
        type: object[]
        description: "Array of row objects"
      - name: sort
        type: object[]
        description: "Sort keys [{field, direction}]"
    outputs:
      - name: sorted
        type: object[]
        description: "Sorted rows"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.rowsGroupAggregate:
    type: utility
    description: "Groups rows by key and computes aggregates (count/sum/avg/min/max)"
    path: "rows-group-aggregate"
    domain_rules:
      - id: grouping
        description: "Must group by specified key(s)"
      - id: aggregates
        description: "Must support count, sum, avg, min, max"
      - id: null_handling
        description: "Must handle null values in aggregates"
    inputs:
      - name: rows
        type: object[]
        description: "Array of row objects"
      - name: groupBy
        type: string
        description: "Field to group by (supports dot notation for nested fields)"
      - name: aggregates
        type: object[]
        description: "Aggregate definitions [{field, operation}]"
    outputs:
      - name: groups
        type: GroupAggregateResult
        description: "Grouped rows with aggregates and group count"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.rowsJoin:
    type: utility
    description: "Joins two datasets on keys with inner/left/right/full join support"
    path: "rows-join"
    domain_rules:
      - id: join_types
        description: "Must support inner, left, right, and full joins"
      - id: key_matching
        description: "Must build index for efficient matching"
      - id: field_merging
        description: "Must handle field name conflicts with prefixing"
    inputs:
      - name: left
        type: object[]
        description: "Left dataset"
      - name: right
        type: object[]
        description: "Right dataset"
      - name: leftKey
        type: string
        description: "Field name in left array to join on"
      - name: rightKey
        type: string
        description: "Field name in right array to join on"
      - name: type
        type: string
        optional: true
        description: "Join type: inner, left, right, or full (default: inner)"
    outputs:
      - name: rows
        type: JoinResult
        description: "Joined rows with match statistics"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.dedupeByKey:
    type: utility
    description: "Deduplicates rows by key, keeping first or last occurrence"
    path: "dedupe-by-key"
    domain_rules:
      - id: deduplication
        description: "Must use Map for efficient deduplication"
      - id: keep_strategy
        description: "Must support keeping first or last occurrence"
      - id: key_function
        description: "Must support simple field or composite key with dot notation"
    inputs:
      - name: rows
        type: object[]
        description: "Array of row objects"
      - name: key
        type: string | string[]
        description: "Field(s) to dedupe on, supports dot notation for nested fields"
      - name: keepLast
        type: boolean
        optional: true
        description: "If true, keeps last occurrence; if false, keeps first (default: false)"
    outputs:
      - name: rows
        type: DedupeResult
        description: "Deduplicated rows with statistics"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.pivot:
    type: utility
    description: "Pivots data long-to-wide with row key, column key, and value key"
    path: "pivot"
    domain_rules:
      - id: pivot_logic
        description: "Must transform rows to pivoted columns"
      - id: aggregation
        description: "Must aggregate when multiple values exist"
      - id: naming
        description: "Must generate clear column names"
    inputs:
      - name: rows
        type: object[]
        description: "Array of row objects"
      - name: rowKey
        type: string
        description: "Field to use as row identifier"
      - name: columnKey
        type: string
        description: "Field whose values become column names"
      - name: valueKey
        type: string
        description: "Field containing values to pivot"
    outputs:
      - name: pivoted
        type: PivotResult
        description: "Pivoted data with columns and metadata"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.normalizeWhitespace:
    type: utility
    description: "Normalizes newlines, trims, and collapses excessive spaces"
    path: "normalize-whitespace"
    domain_rules:
      - id: normalization
        description: "Must handle various whitespace types"
      - id: modes
        description: "Must support different normalization modes"
      - id: preservation
        description: "Must optionally preserve paragraph breaks"
    inputs:
      - name: text
        type: string
        description: "Text to normalize"
      - name: mode
        type: string
        optional: true
        description: "Mode: collapse, trim, paragraphs"
    outputs:
      - name: normalized
        type: string
        description: "Normalized text"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.urlNormalize:
    type: utility
    description: "Canonicalizes URLs for deduplication and caching"
    path: "url-normalize"
    domain_rules:
      - id: normalization
        description: "Must normalize protocol, host, path, and query"
      - id: fragment_handling
        description: "Must strip fragments by default"
      - id: query_ordering
        description: "Must sort query parameters"
    inputs:
      - name: url
        type: string
        description: "URL to normalize"
    outputs:
      - name: normalized
        type: string
        description: "Normalized URL"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.textChunk:
    type: utility
    description: "Splits text into chunks with overlap for downstream processing"
    path: "text-chunk"
    domain_rules:
      - id: chunking
        description: "Must split by character count with overlap"
      - id: boundaries
        description: "Should prefer sentence boundaries when possible"
      - id: metadata
        description: "Must include chunk index and offsets"
    inputs:
      - name: text
        type: string
        description: "Text to chunk"
      - name: maxChars
        type: number
        description: "Maximum characters per chunk"
      - name: overlapChars
        type: number
        optional: true
        description: "Overlap between chunks"
    outputs:
      - name: chunks
        type: TextChunks
        description: "Array of text chunks with metadata"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.base64Decode:
    type: utility
    description: "Decode base64 encoded data to string with support for multiple output encodings"
    path: "base64-decode"
    domain_rules:
      - id: encoding_support
        description: "Must support utf8, binary, and hex output encodings"
      - id: error_handling
        description: "Must handle invalid base64 input gracefully"
    inputs:
      - name: base64
        type: string
        description: "The base64 encoded data to decode"
      - name: encoding
        type: string
        optional: true
        description: "Character encoding for output (utf8, binary, hex)"
    outputs:
      - name: result
        type: Base64DecodeResult
        description: "Object with decoded string and byte length"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.base64Encode:
    type: utility
    description: "Encode string or buffer to base64 format with support for multiple character encodings"
    path: "base64-encode"
    domain_rules:
      - id: encoding_support
        description: "Must support utf8, binary, and hex input encodings"
      - id: standard_output
        description: "Must output valid base64 string"
    inputs:
      - name: data
        type: string
        description: "The data to encode"
      - name: encoding
        type: string
        optional: true
        description: "Character encoding (utf8, binary, hex)"
    outputs:
      - name: result
        type: Base64EncodeResult
        description: "Object with base64 encoded string and byte length"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.dateParse:
    type: utility
    description: "Parse dates from natural language text like 'tomorrow at 3pm' or 'next Friday'"
    path: "date-parse"
    domain_rules:
      - id: natural_language
        description: "Must parse natural language date expressions"
      - id: reference_date
        description: "Must support custom reference date for relative dates"
      - id: multiple_dates
        description: "Must extract multiple dates from text"
    inputs:
      - name: text
        type: string
        description: "Text containing date/time expressions"
      - name: referenceDate
        type: string
        optional: true
        description: "ISO date string to use as reference for relative dates"
      - name: strict
        type: boolean
        optional: true
        description: "Use strict parsing mode for more accurate results"
    outputs:
      - name: result
        type: DateParseResult
        description: "Array of parsed dates with original text and timestamps"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.hashText:
    type: utility
    description: "Hash text using cryptographic algorithms (MD5, SHA-1, SHA-256, SHA-512)"
    path: "hash-text"
    domain_rules:
      - id: algorithm_support
        description: "Must support md5, sha1, sha256, sha512 algorithms"
      - id: hex_output
        description: "Must output hexadecimal hash digest"
    inputs:
      - name: text
        type: string
        description: "The text to hash"
      - name: algorithm
        type: string
        description: "Hash algorithm (md5, sha1, sha256, sha512)"
    outputs:
      - name: result
        type: HashTextResult
        description: "Object with hash digest, algorithm used, and input length"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.htmlToMarkdown:
    type: utility
    description: "Convert HTML to markdown with customizable formatting options"
    path: "html-to-markdown"
    domain_rules:
      - id: html_conversion
        description: "Must use turndown for HTML to markdown conversion"
      - id: element_mapping
        description: "Must convert common HTML elements to markdown equivalents"
      - id: custom_options
        description: "Should support customizable formatting options"
    inputs:
      - name: html
        type: string
        description: "The HTML string to convert"
      - name: options
        type: object
        optional: true
        description: "Optional configuration for markdown formatting (headingStyle, bulletListMarker)"
    outputs:
      - name: result
        type: HtmlToMarkdownResult
        description: "Object with markdown output and word count"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.jsonPathQuery:
    type: utility
    description: "Query JSON data using JSONPath expressions like '$.users[?(@.age > 18)].name'"
    path: "json-path-query"
    domain_rules:
      - id: jsonpath_standard
        description: "Must support standard JSONPath syntax"
      - id: filter_expressions
        description: "Must support filter expressions"
      - id: result_paths
        description: "Should return matched paths along with values"
    inputs:
      - name: json
        type: object | array
        description: "JSON data to query"
      - name: path
        type: string
        description: "JSONPath expression to evaluate"
    outputs:
      - name: result
        type: JsonPathQueryResult
        description: "Query results with count and matched paths"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.markdownToHtml:
    type: utility
    description: "Convert markdown to HTML with optional GitHub Flavored Markdown and sanitization"
    path: "markdown-to-html"
    domain_rules:
      - id: gfm_support
        description: "Must support GitHub Flavored Markdown"
      - id: sanitization
        description: "Should support optional HTML sanitization"
      - id: heading_extraction
        description: "Should extract headings for TOC generation"
    inputs:
      - name: markdown
        type: string
        description: "The markdown string to convert"
      - name: options
        type: object
        optional: true
        description: "Optional configuration for GFM and sanitization"
    outputs:
      - name: result
        type: MarkdownToHtmlResult
        description: "Object with HTML output and extracted headings"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.regexExtract:
    type: utility
    description: "Extract all regex matches from text with optional capture group support"
    path: "regex-extract"
    domain_rules:
      - id: regex_execution
        description: "Must properly execute regex with specified flags"
      - id: capture_groups
        description: "Must support capture group extraction"
      - id: match_metadata
        description: "Should include match indices and counts"
    inputs:
      - name: text
        type: string
        description: "The text to search"
      - name: pattern
        type: string
        description: "Regular expression pattern"
      - name: flags
        type: string
        optional: true
        description: "Regular expression flags (g, i, m, s, u, y)"
      - name: groups
        type: boolean
        optional: true
        description: "Return capture groups as objects"
    outputs:
      - name: result
        type: RegexExtractResult
        description: "Object with matches array, match count, and hasMatches flag"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.schemaInfer:
    type: utility
    description: "Infer JSON Schema from sample data objects"
    path: "schema-infer"
    domain_rules:
      - id: type_inference
        description: "Must infer types from sample values"
      - id: schema_generation
        description: "Must generate valid JSON Schema"
      - id: multiple_samples
        description: "Should handle multiple sample objects for better inference"
    inputs:
      - name: samples
        type: array
        description: "Array of sample data objects to analyze"
      - name: options
        type: object
        optional: true
        description: "Schema generation options"
    outputs:
      - name: result
        type: SchemaInferResult
        description: "Generated JSON Schema with metadata"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.templateRender:
    type: utility
    description: "Render mustache-style templates with data and track variable usage"
    path: "template-render"
    domain_rules:
      - id: mustache_syntax
        description: "Must support {{variable}} placeholder syntax"
      - id: variable_tracking
        description: "Must track used and unused variables"
      - id: html_escaping
        description: "Should support optional HTML escaping"
    inputs:
      - name: template
        type: string
        description: "The mustache-style template string with {{variable}} placeholders"
      - name: data
        type: object
        description: "Data object to substitute into the template"
      - name: options
        type: object
        optional: true
        description: "Optional settings like HTML escaping"
    outputs:
      - name: result
        type: TemplateRenderResult
        description: "Rendered template with tracking of used and unused variables"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  data.urlParse:
    type: utility
    description: "Parse URL into protocol, hostname, port, pathname, search params, and hash"
    path: "url-parse"
    domain_rules:
      - id: url_api
        description: "Must use URL Web API for parsing"
      - id: search_params
        description: "Must parse query string into key-value pairs"
      - id: all_components
        description: "Must extract all URL components"
    inputs:
      - name: url
        type: string
        description: "The URL string to parse"
    outputs:
      - name: result
        type: UrlParseResult
        description: "Object with all URL components and parsed search parameters"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # D) Engineering & Ops Helpers (15 tools)
  # ---------------------------------------------------------------------------
  eng.diffTextUnified:
    type: utility
    description: "Produces unified diff between two strings for reviews and patch previews"
    path: "diff-text-unified"
    domain_rules:
      - id: diff_algorithm
        description: "Must use diff library for unified diff"
      - id: context_lines
        description: "Must include context lines"
      - id: line_numbers
        description: "Must include line numbers"
    inputs:
      - name: original
        type: string
        description: "Original text to compare from"
      - name: modified
        type: string
        description: "Modified text to compare to"
      - name: contextLines
        type: number
        optional: true
        description: "Number of context lines to show around changes (default: 3)"
    outputs:
      - name: diff
        type: DiffResult
        description: "Unified diff output with statistics"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  eng.stacktraceParse:
    type: utility
    description: "Parses stack traces into frames and highlights likely app frames vs library frames"
    path: "stacktrace-parse"
    domain_rules:
      - id: parsing
        description: "Must use stacktrace-parser library"
      - id: classification
        description: "Must classify app vs library frames"
      - id: language_support
        description: "Must support JavaScript/TypeScript stack traces"
    inputs:
      - name: stack
        type: string
        description: "Stack trace text"
    outputs:
      - name: parsed
        type: StacktraceParsed
        description: "Parsed stack trace with classified frames"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  eng.errorLogTriage:
    type: utility
    description: "Buckets logs into likely causes with recommended next checks"
    path: "error-log-triage"
    domain_rules:
      - id: pattern_matching
        description: "Must match common error patterns"
      - id: categorization
        description: "Must categorize as network, auth, timeout, schema, etc."
      - id: recommendations
        description: "Must provide actionable next steps"
    inputs:
      - name: logs
        type: string
        description: "Error log content"
    outputs:
      - name: triage
        type: ErrorTriage
        description: "Categorized errors with recommendations"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  eng.conventionalCommitSuggest:
    type: utility
    description: "Suggests conventional commit message from a change summary"
    path: "conventional-commit-suggest"
    domain_rules:
      - id: classification
        description: "Must classify as feat, fix, docs, refactor, etc."
      - id: format
        description: "Must follow conventional commit format"
      - id: scope_detection
        description: "Should suggest scope if detectable"
    inputs:
      - name: summary
        type: string
        description: "Summary of changes made"
    outputs:
      - name: commit
        type: CommitMessage
        description: "Suggested commit message"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  eng.envVarDocsGenerate:
    type: utility
    description: "Generates environment variable documentation table from schema"
    path: "env-var-docs-generate"
    domain_rules:
      - id: table_format
        description: "Must generate markdown table"
      - id: required_marking
        description: "Must indicate required vs optional"
      - id: examples
        description: "Must include example values"
    inputs:
      - name: vars
        type: object[]
        description: "Environment variable definitions"
    outputs:
      - name: docs
        type: string
        description: "Markdown documentation"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  eng.openapiSnippetBuild:
    type: utility
    description: "Builds minimal OpenAPI snippet from endpoint metadata"
    path: "openapi-snippet-build"
    domain_rules:
      - id: openapi_format
        description: "Must generate valid OpenAPI 3.0 YAML"
      - id: schema_generation
        description: "Must generate request/response schemas"
      - id: minimal
        description: "Must focus on essential elements"
    inputs:
      - name: endpoints
        type: object[]
        description: "Endpoint definitions [{method, path, params, response}]"
    outputs:
      - name: openapi
        type: string
        description: "OpenAPI YAML snippet"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  eng.dependencyAuditLite:
    type: utility
    description: "Heuristic audit for duplicates, suspicious version ranges, and heavy deps"
    path: "dependency-audit-lite"
    domain_rules:
      - id: duplicate_detection
        description: "Must detect duplicate packages at different versions"
      - id: range_analysis
        description: "Must flag suspicious version ranges"
      - id: size_warnings
        description: "Must warn about known heavy packages"
    inputs:
      - name: packageJson
        type: object
        description: "package.json content"
    outputs:
      - name: audit
        type: DependencyAudit
        description: "Audit results with recommendations"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  eng.configNormalize:
    type: utility
    description: "Applies defaults and coercions to config objects"
    path: "config-normalize"
    domain_rules:
      - id: defaults
        description: "Must apply default values from schema"
      - id: coercion
        description: "Must coerce types where safe"
      - id: validation
        description: "Must validate against schema"
    inputs:
      - name: config
        type: object
        description: "Raw configuration object"
      - name: schema
        type: object
        description: "Schema with defaults"
    outputs:
      - name: normalized
        type: ConfigNormalized
        description: "Normalized config with applied defaults"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  eng.testCaseGenerate:
    type: utility
    description: "Generates test cases from requirements with scenarios and expected results"
    path: "test-case-generate"
    domain_rules:
      - id: scenario_generation
        description: "Must generate happy path and edge cases"
      - id: structure
        description: "Must include steps and expected results"
      - id: traceability
        description: "Should link back to requirements"
    inputs:
      - name: requirements
        type: string
        description: "Requirements to generate tests for"
    outputs:
      - name: testCases
        type: TestCase[]
        description: "Generated test cases"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  eng.releaseChecklist:
    type: utility
    description: "Generates pre-release checklist tailored to stack"
    path: "release-checklist"
    domain_rules:
      - id: stack_awareness
        description: "Must customize for web/app/library stacks"
      - id: critical_items
        description: "Must mark critical vs optional items"
      - id: categories
        description: "Must organize by category (code, docs, ops)"
    inputs:
      - name: stack
        type: string
        description: "Technology stack (nextjs, node-library, react-app)"
    outputs:
      - name: checklist
        type: ReleaseChecklist
        description: "Tailored release checklist"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  ops.monitoringGapAnalysis:
    type: utility
    description: "Suggests missing monitors and SLO signals from services and incidents"
    path: "monitoring-gap-analysis"
    domain_rules:
      - id: signal_analysis
        description: "Must check for latency, errors, saturation coverage"
      - id: incident_correlation
        description: "Must correlate gaps with past incidents"
      - id: recommendations
        description: "Must provide specific monitor recommendations"
    inputs:
      - name: services
        type: object[]
        description: "Service definitions"
      - name: incidents
        type: object[]
        optional: true
        description: "Past incident records"
    outputs:
      - name: gaps
        type: MonitoringGaps
        description: "Identified gaps with recommendations"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  ops.sloDraft:
    type: utility
    description: "Drafts SLOs with SLI definitions, targets, and alerting hints"
    path: "slo-draft"
    domain_rules:
      - id: sli_definition
        description: "Must define measurable SLIs"
      - id: targets
        description: "Must suggest realistic targets"
      - id: alerting
        description: "Must include burn rate alerting hints"
    inputs:
      - name: serviceDesc
        type: string
        description: "Description of the service"
    outputs:
      - name: slo
        type: SLODraft
        description: "SLO specification draft"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  ops.postmortemActionExtractor:
    type: utility
    description: "Extracts action items with owners and dates from postmortem text"
    path: "postmortem-action-extractor"
    domain_rules:
      - id: action_detection
        description: "Must detect action items from cue phrases"
      - id: owner_extraction
        description: "Must extract owner names"
      - id: date_extraction
        description: "Must extract due dates if mentioned"
    inputs:
      - name: text
        type: string
        description: "Postmortem text"
    outputs:
      - name: actions
        type: ActionItem[]
        description: "Extracted action items"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # E) Security & Compliance (10 tools)
  # ---------------------------------------------------------------------------
  sec.urlRiskHeuristic:
    type: utility
    description: "Flags suspicious URLs using punycode, homoglyph, and TLD pattern detection"
    path: "url-risk-heuristic"
    domain_rules:
      - id: punycode_detection
        description: "Must detect punycode in domains"
      - id: homoglyph_detection
        description: "Must check for homoglyph substitutions"
      - id: tld_analysis
        description: "Must flag unusual TLDs"
    inputs:
      - name: url
        type: string
        description: "URL to analyze"
    outputs:
      - name: risk
        type: UrlRisk
        description: "Risk assessment with signals"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  sec.secretScanText:
    type: utility
    description: "Detects potential secrets (API keys, tokens, private keys) in text"
    path: "secret-scan-text"
    domain_rules:
      - id: pattern_library
        description: "Must use comprehensive secret patterns"
      - id: false_positive_reduction
        description: "Must minimize false positives"
      - id: severity_levels
        description: "Must indicate severity per finding"
    inputs:
      - name: text
        type: string
        description: "Text to scan for secrets"
    outputs:
      - name: findings
        type: SecretScan
        description: "Detected secrets with locations"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  sec.redactSecrets:
    type: utility
    description: "Redacts detected secrets from text and returns a redaction report"
    path: "redact-secrets"
    domain_rules:
      - id: redaction
        description: "Must fully redact secrets"
      - id: markers
        description: "Must use consistent redaction markers"
      - id: fingerprints
        description: "Must keep hashed fingerprints for audit"
    inputs:
      - name: text
        type: string
        description: "Text containing secrets"
    outputs:
      - name: result
        type: RedactionResult
        description: "Redacted text with report"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  sec.cspCompose:
    type: utility
    description: "Builds a CSP header string from allowed origins and directives"
    path: "csp-compose"
    domain_rules:
      - id: directive_building
        description: "Must build valid CSP directives"
      - id: best_practices
        description: "Must follow CSP best practices"
      - id: header_format
        description: "Must output valid header string"
    inputs:
      - name: allow
        type: object
        description: "Allowed sources per directive"
    outputs:
      - name: csp
        type: CSPHeader
        description: "CSP header configuration"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  sec.hardeningChecklistWeb:
    type: utility
    description: "Creates web app hardening checklist for headers, cookies, deps, and auth"
    path: "hardening-checklist-web"
    domain_rules:
      - id: coverage
        description: "Must cover headers, cookies, deps, auth"
      - id: prioritization
        description: "Must prioritize by impact"
      - id: stack_awareness
        description: "Must adapt to specified stack"
    inputs:
      - name: stack
        type: string
        description: "Technology stack"
      - name: context
        type: object
        optional: true
        description: "Additional context"
    outputs:
      - name: checklist
        type: HardeningChecklist
        description: "Security hardening checklist"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  sec.htmlSanitize:
    type: utility
    description: "Sanitize HTML to prevent XSS attacks with customizable allowed tags and attributes"
    path: "html-sanitize"
    domain_rules:
      - id: xss_prevention
        description: "Must remove script tags, event handlers, and dangerous attributes"
      - id: allowlist_based
        description: "Must use allowlist-based approach for tags and attributes"
      - id: removal_tracking
        description: "Should track what was removed for transparency"
    inputs:
      - name: html
        type: string
        description: "The HTML string to sanitize"
      - name: options
        type: object
        optional: true
        description: "Optional configuration for allowed tags and attributes"
    outputs:
      - name: result
        type: HtmlSanitizeResult
        description: "Object with sanitized HTML, removal count, and warnings about removed elements"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  compliance.dataClassificationHeuristic:
    type: utility
    description: "Labels fields as PII/sensitive based on names and sample values"
    path: "data-classification-heuristic"
    domain_rules:
      - id: pattern_detection
        description: "Must detect email, phone, address, ID patterns"
      - id: name_analysis
        description: "Must analyze field names for PII hints"
      - id: confidence
        description: "Must report confidence levels"
    inputs:
      - name: rows
        type: object[]
        description: "Sample data rows"
    outputs:
      - name: classification
        type: DataClassification
        description: "Field classifications"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  compliance.retentionPolicyDraft:
    type: utility
    description: "Drafts data retention/deletion policy from system requirements"
    path: "retention-policy-draft"
    domain_rules:
      - id: policy_structure
        description: "Must include retention periods and deletion procedures"
      - id: legal_considerations
        description: "Must note legal hold requirements"
      - id: data_types
        description: "Must differentiate by data type"
    inputs:
      - name: requirements
        type: string
        description: "System and compliance requirements"
    outputs:
      - name: policy
        type: RetentionPolicy
        description: "Draft retention policy"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  compliance.dpiaOutline:
    type: utility
    description: "Drafts DPIA outline with purpose, risks, mitigations, and necessity assessment"
    path: "dpia-outline"
    domain_rules:
      - id: dpia_structure
        description: "Must follow DPIA structure"
      - id: risk_identification
        description: "Must identify privacy risks"
      - id: mitigations
        description: "Must suggest mitigations"
    inputs:
      - name: featureDesc
        type: string
        description: "Feature or system description"
    outputs:
      - name: dpia
        type: DPIAOutline
        description: "DPIA outline document"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  compliance.accessControlMatrix:
    type: utility
    description: "Generates RBAC permissions matrix from roles and resources"
    path: "access-control-matrix"
    domain_rules:
      - id: matrix_generation
        description: "Must generate complete role/resource matrix"
      - id: markdown_output
        description: "Must output as markdown table"
      - id: gap_detection
        description: "Should flag missing permissions"
    inputs:
      - name: roles
        type: string[]
        description: "Role names"
      - name: resources
        type: string[]
        description: "Resource names"
    outputs:
      - name: matrix
        type: AccessMatrix
        description: "RBAC matrix"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # F) Quantitative / Statistics (10 tools)
  # ---------------------------------------------------------------------------
  stats.bootstrapCI:
    type: utility
    description: "Computes bootstrap confidence intervals for mean, median, or custom statistic"
    path: "bootstrap-ci"
    domain_rules:
      - id: resampling
        description: "Must perform proper bootstrap resampling (1000+ iterations)"
      - id: percentile_method
        description: "Must use percentile method for CI"
      - id: seed_support
        description: "Must support seeding for reproducibility"
    inputs:
      - name: samples
        type: number[]
        description: "Data samples"
      - name: statistic
        type: string
        description: "Statistic: mean, median, or custom"
      - name: confidence
        type: number
        optional: true
        description: "Confidence level (default: 0.95)"
    outputs:
      - name: ci
        type: ConfidenceInterval
        description: "Bootstrap confidence interval"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  stats.permutationTest:
    type: utility
    description: "Nonparametric hypothesis test using permutation resampling"
    path: "permutation-test"
    domain_rules:
      - id: permutation_logic
        description: "Must shuffle labels and compute test statistic"
      - id: iteration_count
        description: "Must use sufficient permutations (1000+)"
      - id: p_value
        description: "Must compute exact p-value from permutation distribution"
    inputs:
      - name: groupA
        type: number[]
        description: "First group samples"
      - name: groupB
        type: number[]
        description: "Second group samples"
    outputs:
      - name: result
        type: HypothesisTest
        description: "Permutation test result with p-value"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  stats.effectSizeSuite:
    type: utility
    description: "Computes effect sizes: Cohen's d, odds ratio, r, eta² for proper reporting"
    path: "effect-size-suite"
    domain_rules:
      - id: measures
        description: "Must support Cohen's d, r, odds ratio, eta²"
      - id: interpretation
        description: "Must provide effect size interpretation (small/medium/large)"
      - id: confidence_intervals
        description: "Should include CI for effect size"
    inputs:
      - name: type
        type: string
        description: "Effect size type: cohensD, oddsRatio, r, etaSquared"
      - name: dataA
        type: number[]
        description: "First group data"
      - name: dataB
        type: number[]
        description: "Second group data"
    outputs:
      - name: effectSize
        type: EffectSize
        description: "Effect size with interpretation"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  stats.multipleTestingAdjust:
    type: utility
    description: "Applies Bonferroni, Holm, or Benjamini-Hochberg corrections to p-values"
    path: "multiple-testing-adjust"
    domain_rules:
      - id: methods
        description: "Must support Bonferroni, Holm, and BH methods"
      - id: sorting
        description: "Must handle p-value ordering correctly"
      - id: output
        description: "Must return adjusted p-values in original order"
    inputs:
      - name: pValues
        type: number[]
        description: "Array of p-values"
      - name: method
        type: string
        description: "Adjustment method: bonferroni, holm, bh"
    outputs:
      - name: adjusted
        type: number[]
        description: "Adjusted p-values"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  stats.linearRegressionOLS:
    type: utility
    description: "Fits OLS regression and returns coefficients with residual diagnostics"
    path: "linear-regression-ols"
    domain_rules:
      - id: algorithm
        description: "Must use proper OLS algorithm"
      - id: diagnostics
        description: "Must return R², residuals, and coefficient SEs"
      - id: numerical_stability
        description: "Must handle multicollinearity warnings"
    inputs:
      - name: X
        type: number[][]
        description: "Feature matrix (rows are observations)"
      - name: y
        type: number[]
        description: "Target values"
    outputs:
      - name: regression
        type: RegressionResult
        description: "Regression results with diagnostics"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  stats.logisticRegression:
    type: utility
    description: "Fits logistic regression for binary outcomes with weights and metrics"
    path: "logistic-regression"
    domain_rules:
      - id: algorithm
        description: "Must use proper logistic regression algorithm"
      - id: metrics
        description: "Must return accuracy, AUC if possible"
      - id: convergence
        description: "Must report convergence status"
    inputs:
      - name: X
        type: number[][]
        description: "Feature matrix"
      - name: y
        type: number[]
        description: "Binary labels (0/1)"
    outputs:
      - name: model
        type: LogisticRegressionResult
        description: "Model with weights and metrics"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  causal.diffInDiff:
    type: utility
    description: "Difference-in-differences estimate with parallel trends assumption check"
    path: "diff-in-diff"
    domain_rules:
      - id: did_calculation
        description: "Must compute proper DiD estimate"
      - id: assumptions
        description: "Must report on parallel trends assumption"
      - id: standard_errors
        description: "Must compute standard errors"
    inputs:
      - name: rows
        type: object[]
        description: "Panel data rows"
      - name: unit
        type: string
        description: "Unit identifier field"
      - name: time
        type: string
        description: "Time period field"
      - name: treated
        type: string
        description: "Treatment indicator field"
      - name: y
        type: string
        description: "Outcome field"
    outputs:
      - name: estimate
        type: DiDEstimate
        description: "DiD estimate with diagnostics"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  bayes.betaBinomialUpdate:
    type: utility
    description: "Bayesian update for conversion rates with Beta prior, returns posterior and credible interval"
    path: "beta-binomial-update"
    domain_rules:
      - id: posterior
        description: "Must compute Beta posterior correctly"
      - id: credible_interval
        description: "Must compute credible interval"
      - id: prior_sensitivity
        description: "Should report prior impact"
    inputs:
      - name: priorAlpha
        type: number
        description: "Prior alpha parameter (represents prior successes + 1)"
      - name: priorBeta
        type: number
        description: "Prior beta parameter (represents prior failures + 1)"
      - name: successes
        type: number
        description: "Observed successes"
      - name: trials
        type: number
        description: "Total trials"
      - name: credibleLevel
        type: number
        optional: true
        description: "Credible interval level (default: 0.95 for 95% interval)"
    outputs:
      - name: posterior
        type: BetaBinomialPosterior
        description: "Posterior distribution with credible interval and statistics"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  stats.timeSeriesDecomposeLite:
    type: utility
    description: "Decomposes time series into trend, seasonality, and residual components"
    path: "time-series-decompose-lite"
    domain_rules:
      - id: decomposition
        description: "Must separate trend, seasonal, and residual"
      - id: period_handling
        description: "Must handle specified seasonality period"
      - id: method
        description: "Must use moving average for trend"
    inputs:
      - name: t
        type: number[]
        description: "Time indices"
      - name: y
        type: number[]
        description: "Values"
      - name: period
        type: number
        description: "Seasonality period"
    outputs:
      - name: decomposition
        type: TimeSeriesDecomposition
        description: "Decomposed components"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  stats.anomalyDetectMAD:
    type: utility
    description: "Robust anomaly detection using median absolute deviation"
    path: "anomaly-detect-mad"
    domain_rules:
      - id: mad_calculation
        description: "Must compute MAD correctly"
      - id: threshold
        description: "Must use configurable threshold"
      - id: robustness
        description: "Must be robust to outliers in calculation"
    inputs:
      - name: series
        type: number[]
        description: "Data series"
      - name: threshold
        type: number
        optional: true
        description: "MAD threshold (default: 3)"
    outputs:
      - name: anomalies
        type: AnomalyResult
        description: "Detected anomalies with scores"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # G) Agent Ops / Recipes / Routing / Eval (20 tools)
  # ---------------------------------------------------------------------------
  agent.recipeEmit:
    type: utility
    description: "Emits canonical workflow JSON with steps, params, artifacts, and checks"
    path: "recipe-emit"
    domain_rules:
      - id: schema
        description: "Must output valid recipe JSON schema"
      - id: normalization
        description: "Must normalize step definitions"
      - id: validation
        description: "Must validate recipe structure"
    inputs:
      - name: recipeName
        type: string
        description: "Recipe identifier"
      - name: options
        type: object
        description: "Recipe configuration options"
    outputs:
      - name: recipe
        type: Recipe
        description: "Canonical recipe specification"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.recipeHash:
    type: utility
    description: "Produces stable hash ID for recipe deduplication and versioning"
    path: "recipe-hash"
    domain_rules:
      - id: stability
        description: "Must use json-stable-stringify for consistent ordering"
      - id: hash_algorithm
        description: "Must use crypto.createHash for hashing"
      - id: collision_resistance
        description: "Must use SHA-256 or better"
    inputs:
      - name: workflow
        type: object
        description: "Workflow object to hash"
    outputs:
      - name: hash
        type: string
        description: "Stable hash ID"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.workflowValidateIO:
    type: utility
    description: "Validates that each step's output type matches next step's input type"
    path: "workflow-validate-io"
    domain_rules:
      - id: type_checking
        description: "Must check input/output type compatibility"
      - id: error_reporting
        description: "Must report mismatches with step details"
      - id: catalog_lookup
        description: "Must look up tool types from catalog"
    inputs:
      - name: steps
        type: object[]
        description: "Workflow steps to validate"
    outputs:
      - name: validation
        type: WorkflowValidation
        description: "Validation result with any mismatches"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.workflowAutoRepair:
    type: utility
    description: "Inserts adapter steps when input/output types are mismatched"
    path: "workflow-auto-repair"
    domain_rules:
      - id: adapter_insertion
        description: "Must insert appropriate adapters (html→text, json-repair, etc.)"
      - id: rule_table
        description: "Must use adapter lookup table"
      - id: minimal_changes
        description: "Must make minimal necessary repairs"
    inputs:
      - name: steps
        type: object[]
        description: "Workflow steps with potential mismatches"
    outputs:
      - name: repaired
        type: object[]
        description: "Repaired workflow steps"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.toolSelectionPlan:
    type: utility
    description: "Creates tool selection policy specifying when to use which tools"
    path: "tool-selection-plan"
    domain_rules:
      - id: policy_generation
        description: "Must generate clear selection rules"
      - id: goal_mapping
        description: "Must map goals to tool choices"
      - id: rationale
        description: "Must include rationale for each rule"
    inputs:
      - name: tools
        type: object[]
        description: "Available tools"
      - name: goals
        type: string[]
        description: "Agent goals"
    outputs:
      - name: policy
        type: ToolSelectionPolicy
        description: "Tool selection policy"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.evalFixtureBuild:
    type: utility
    description: "Converts conversations into eval fixtures with inputs and expected tool calls"
    path: "eval-fixture-build"
    domain_rules:
      - id: fixture_format
        description: "Must output JSONL-compatible fixtures"
      - id: schema
        description: "Must follow strict eval schema"
      - id: extraction
        description: "Must extract tool calls from conversations"
    inputs:
      - name: conversations
        type: object[]
        description: "Conversation transcripts"
    outputs:
      - name: fixtures
        type: EvalFixture[]
        description: "Evaluation fixtures"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.toolCallAccuracyScore:
    type: utility
    description: "Scores predicted tool calls vs expected with exact, top-k, and partial credit"
    path: "tool-call-accuracy-score"
    domain_rules:
      - id: scoring_methods
        description: "Must support exact, top-k, and partial matching"
      - id: metrics
        description: "Must compute precision, recall, F1"
      - id: detailed_breakdown
        description: "Must provide per-example breakdown"
    inputs:
      - name: expected
        type: object[]
        description: "Expected tool calls"
      - name: predicted
        type: object[]
        description: "Predicted tool calls"
    outputs:
      - name: scores
        type: AccuracyScores
        description: "Accuracy metrics"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.coverageTracker:
    type: utility
    description: "Tracks coverage across domains, artifacts, and roles for recipe library"
    path: "coverage-tracker"
    domain_rules:
      - id: coverage_computation
        description: "Must compute coverage by category"
      - id: gap_identification
        description: "Must identify uncovered areas"
      - id: histograms
        description: "Must provide distribution data"
    inputs:
      - name: recipes
        type: object[]
        description: "Recipe library"
    outputs:
      - name: coverage
        type: CoverageReport
        description: "Coverage analysis"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.noveltyScoreWorkflow:
    type: utility
    description: "Scores workflow uniqueness vs corpus using tool-sequence similarity"
    path: "novelty-score-workflow"
    domain_rules:
      - id: similarity_method
        description: "Must use simhash or minhash over tool IDs"
      - id: scoring
        description: "Must output 0-1 novelty score"
      - id: similar_workflows
        description: "Must identify most similar existing workflows"
    inputs:
      - name: workflow
        type: object
        description: "Workflow to score"
      - name: corpus
        type: object[]
        description: "Existing workflow corpus"
    outputs:
      - name: novelty
        type: NoveltyScore
        description: "Novelty assessment"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.recipeGenerateFromGrammar:
    type: utility
    description: "Expands workflow templates into concrete recipes using grammar rules"
    path: "recipe-generate-from-grammar"
    domain_rules:
      - id: grammar_expansion
        description: "Must follow Acquire→Extract→Analyze→Output pattern"
      - id: slot_filling
        description: "Must fill slots from tool catalog"
      - id: quota_sampling
        description: "Must sample to requested count"
    inputs:
      - name: templates
        type: object[]
        description: "Workflow templates"
      - name: catalog
        type: object[]
        description: "Tool catalog"
      - name: n
        type: number
        description: "Number of recipes to generate"
    outputs:
      - name: recipes
        type: object[]
        description: "Generated recipes"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.recipeCurateRank:
    type: utility
    description: "Filters, dedupes, and ranks recipe candidates by coherence, novelty, and coverage"
    path: "recipe-curate-rank"
    domain_rules:
      - id: deduplication
        description: "Must dedupe by recipe hash"
      - id: ranking
        description: "Must rank by multiple criteria"
      - id: selection
        description: "Must select to target count"
    inputs:
      - name: candidates
        type: object[]
        description: "Recipe candidates"
      - name: targets
        type: object
        description: "Selection targets"
    outputs:
      - name: curated
        type: object[]
        description: "Curated and ranked recipes"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.workflowCostEstimate:
    type: utility
    description: "Estimates workflow cost in steps, bytes, network calls, and complexity"
    path: "workflow-cost-estimate"
    domain_rules:
      - id: cost_metadata
        description: "Must use per-tool cost metadata"
      - id: aggregation
        description: "Must aggregate across steps"
      - id: categories
        description: "Must break down by cost category"
    inputs:
      - name: steps
        type: object[]
        description: "Workflow steps"
    outputs:
      - name: estimate
        type: CostEstimate
        description: "Cost breakdown"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.guardrailPolicyDraft:
    type: utility
    description: "Drafts operational guardrails for allowed domains, max fetch, redaction, and refusals"
    path: "guardrail-policy-draft"
    domain_rules:
      - id: coverage
        description: "Must cover domains, sizes, redaction, refusals"
      - id: tool_awareness
        description: "Must consider tool capabilities"
      - id: output_format
        description: "Must output executable policy"
    inputs:
      - name: catalog
        type: object[]
        description: "Tool catalog"
      - name: context
        type: object
        description: "Operational context"
    outputs:
      - name: policy
        type: GuardrailPolicy
        description: "Guardrail policy specification"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.promptToWorkflowSkeleton:
    type: utility
    description: "Converts user request into proposed workflow skeleton with steps and rationale"
    path: "prompt-to-workflow-skeleton"
    domain_rules:
      - id: intent_mapping
        description: "Must map intent to workflow structure"
      - id: rationale
        description: "Must provide rationale for each step"
      - id: alternatives
        description: "Must suggest alternatives where applicable"
    inputs:
      - name: prompt
        type: string
        description: "User request prompt"
    outputs:
      - name: skeleton
        type: WorkflowSkeleton
        description: "Proposed workflow structure"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.workflowExplain:
    type: utility
    description: "Produces human-readable explanation of workflow with step purposes and outputs"
    path: "workflow-explain"
    domain_rules:
      - id: explanation
        description: "Must explain why each step exists"
      - id: outputs
        description: "Must describe what each step outputs"
      - id: audience
        description: "Must be readable by non-technical audience"
    inputs:
      - name: steps
        type: object[]
        description: "Workflow steps"
      - name: catalog
        type: object[]
        description: "Tool catalog for metadata"
    outputs:
      - name: explanation
        type: WorkflowExplanation
        description: "Human-readable explanation"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.workflowVariantGenerate:
    type: utility
    description: "Creates meaningful workflow variants for different goals (fast, accurate, low-web)"
    path: "workflow-variant-generate"
    domain_rules:
      - id: variant_rules
        description: "Must apply variant rules per goal"
      - id: compatibility
        description: "Must check variant compatibility"
      - id: meaningful
        description: "Must produce meaningfully different variants"
    inputs:
      - name: workflow
        type: object
        description: "Base workflow"
      - name: goals
        type: string[]
        description: "Variant goals (fast, accurate, low-web)"
    outputs:
      - name: variants
        type: object[]
        description: "Workflow variants"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  agent.recipePublishManifest:
    type: utility
    description: "Builds publish-ready manifests with tags, categories, and readme snippets"
    path: "recipe-publish-manifest"
    domain_rules:
      - id: manifest_format
        description: "Must generate valid publish manifest"
      - id: readme_generation
        description: "Must generate readme snippet"
      - id: tagging
        description: "Must auto-generate tags from content"
    inputs:
      - name: recipes
        type: object[]
        description: "Recipes to publish"
    outputs:
      - name: manifests
        type: PublishManifest[]
        description: "Publish-ready manifests"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # Existing tool (kept for compatibility)
  # ---------------------------------------------------------------------------
  adapter.createBlogPost:
    type: utility
    description: "Creates structured blog posts with frontmatter, metadata, slug generation, word count, and reading time estimation"
    path: "createBlogPost"
    inputs:
      - name: title
        type: string
        description: "The blog post title"
      - name: author
        type: string
        description: "Author name for attribution"
      - name: content
        type: string
        description: "Main body content in markdown"
      - name: tags
        type: string[]
        optional: true
        description: "Categorization tags"
      - name: format
        type: "'markdown' | 'mdx'"
        optional: true
        description: "Output format preference"
      - name: excerpt
        type: string
        optional: true
        description: "Short summary for previews"
    outputs:
      - name: blogPost
        type: BlogPost
        description: "Complete blog post with frontmatter and formatted content"
        measures: [working_implementation, valid_output_structure, ai_sdk_compliance, npm_publishable, readme_documentation]

  # ---------------------------------------------------------------------------
  # H) Sales & Marketing (10 tools)
  # ---------------------------------------------------------------------------
  sales.leadScore:
    type: utility
    description: "Scores leads based on engagement signals like email opens, page visits, form fills, and company fit"
    path: "lead-score"
    domain_rules:
      - id: signal_weighting
        description: "Must weight different engagement signals appropriately"
      - id: score_normalization
        description: "Must normalize score to 0-100 range"
      - id: transparency
        description: "Must explain which signals contributed to score"
    inputs:
      - name: lead
        type: LeadData
        description: "Lead information with engagement history"
    outputs:
      - name: score
        type: LeadScore
        description: "Scored lead with breakdown"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  sales.proposalOutline:
    type: utility
    description: "Generates structured sales proposal outline from opportunity details and customer requirements"
    path: "proposal-outline"
    domain_rules:
      - id: section_structure
        description: "Must include executive summary, solution, pricing, timeline sections"
      - id: customization
        description: "Must incorporate customer-specific details"
    inputs:
      - name: opportunity
        type: object
        description: "Opportunity details including customer, requirements, budget"
      - name: template
        type: string
        optional: true
        description: "Optional proposal template type"
    outputs:
      - name: outline
        type: ProposalOutline
        description: "Structured proposal outline"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  sales.objectionResponse:
    type: utility
    description: "Suggests responses to common sales objections based on objection category and context"
    path: "objection-response"
    domain_rules:
      - id: objection_classification
        description: "Must classify objection type (price, timing, competition, etc.)"
      - id: response_options
        description: "Must provide multiple response strategies"
    inputs:
      - name: objection
        type: string
        description: "The customer objection text"
      - name: context
        type: object
        optional: true
        description: "Deal context and customer info"
    outputs:
      - name: responses
        type: ObjectionResponses
        description: "Suggested responses with rationale"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  marketing.competitorBrief:
    type: utility
    description: "Extracts and structures competitor information from various sources into a competitive brief"
    path: "competitor-brief"
    domain_rules:
      - id: info_extraction
        description: "Must extract pricing, features, positioning, and strengths/weaknesses"
      - id: comparison_matrix
        description: "Must format as comparable matrix"
    inputs:
      - name: competitorName
        type: string
        description: "Name of competitor to analyze"
      - name: sources
        type: string[]
        description: "Source texts/URLs to analyze"
    outputs:
      - name: brief
        type: CompetitorBrief
        description: "Structured competitor analysis"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  marketing.campaignBrief:
    type: utility
    description: "Structures marketing campaign briefs with objectives, audience, channels, and KPIs"
    path: "campaign-brief"
    domain_rules:
      - id: brief_structure
        description: "Must include goals, audience, messaging, channels, budget, timeline"
      - id: measurability
        description: "Must define measurable KPIs"
    inputs:
      - name: campaignGoal
        type: string
        description: "Primary campaign objective"
      - name: product
        type: string
        description: "Product or service being promoted"
      - name: budget
        type: number
        optional: true
        description: "Campaign budget if known"
    outputs:
      - name: brief
        type: CampaignBrief
        description: "Complete campaign brief"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  marketing.socialPostDraft:
    type: utility
    description: "Drafts social media posts optimized for specific platforms with hashtags and call-to-action"
    path: "social-post-draft"
    domain_rules:
      - id: platform_optimization
        description: "Must respect platform character limits and best practices"
      - id: engagement_elements
        description: "Must include hashtags, mentions, or CTAs as appropriate"
    inputs:
      - name: message
        type: string
        description: "Core message to communicate"
      - name: platform
        type: "'twitter' | 'linkedin' | 'instagram' | 'facebook'"
        description: "Target platform"
      - name: tone
        type: string
        optional: true
        description: "Desired tone (professional, casual, etc.)"
    outputs:
      - name: post
        type: SocialPost
        description: "Platform-optimized post"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  marketing.emailSubjectScore:
    type: utility
    description: "Scores email subject lines for open rate potential based on length, urgency, personalization"
    path: "email-subject-score"
    domain_rules:
      - id: scoring_criteria
        description: "Must evaluate length, clarity, urgency, curiosity, personalization"
      - id: suggestions
        description: "Must suggest improvements"
    inputs:
      - name: subjects
        type: string[]
        description: "Subject lines to evaluate"
    outputs:
      - name: scores
        type: SubjectScores
        description: "Scored subjects with recommendations"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  marketing.audiencePersona:
    type: utility
    description: "Creates audience persona profiles from demographic and behavioral data"
    path: "audience-persona"
    domain_rules:
      - id: persona_structure
        description: "Must include demographics, goals, pain points, behaviors"
      - id: actionability
        description: "Must include marketing implications"
    inputs:
      - name: data
        type: object
        description: "Audience data points"
      - name: productContext
        type: string
        description: "Product or service context"
    outputs:
      - name: persona
        type: AudiencePersona
        description: "Complete persona profile"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  marketing.contentCalendarPlan:
    type: utility
    description: "Generates content calendar structure with themes, topics, and posting schedule"
    path: "content-calendar-plan"
    domain_rules:
      - id: calendar_structure
        description: "Must organize by date, theme, channel, content type"
      - id: consistency
        description: "Must maintain consistent posting frequency"
    inputs:
      - name: duration
        type: string
        description: "Calendar duration (week, month, quarter)"
      - name: channels
        type: string[]
        description: "Content channels to plan for"
      - name: themes
        type: string[]
        optional: true
        description: "Content themes or pillars"
    outputs:
      - name: calendar
        type: ContentCalendar
        description: "Structured content calendar"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  marketing.pricingPageCopy:
    type: utility
    description: "Generates pricing page copy with tier names, feature lists, and CTAs"
    path: "pricing-page-copy"
    domain_rules:
      - id: tier_structure
        description: "Must clearly differentiate tiers"
      - id: value_framing
        description: "Must frame features as benefits"
    inputs:
      - name: tiers
        type: object[]
        description: "Pricing tiers with features and prices"
      - name: targetAudience
        type: string
        description: "Primary target audience"
    outputs:
      - name: copy
        type: PricingPageCopy
        description: "Pricing page content"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # I) HR & People Operations (10 tools)
  # ---------------------------------------------------------------------------
  hr.jobDescriptionDraft:
    type: utility
    description: "Generates job descriptions from role requirements with responsibilities, qualifications, and benefits"
    path: "job-description-draft"
    domain_rules:
      - id: jd_structure
        description: "Must include role summary, responsibilities, qualifications, benefits"
      - id: inclusive_language
        description: "Must use inclusive, bias-free language"
    inputs:
      - name: title
        type: string
        description: "Job title"
      - name: requirements
        type: object
        description: "Role requirements and context"
      - name: companyInfo
        type: object
        optional: true
        description: "Company details for context"
    outputs:
      - name: jobDescription
        type: JobDescription
        description: "Complete job description"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  hr.interviewQuestions:
    type: utility
    description: "Generates behavioral and technical interview questions for specific roles"
    path: "interview-questions"
    domain_rules:
      - id: question_types
        description: "Must include behavioral (STAR format) and role-specific questions"
      - id: legal_compliance
        description: "Must avoid legally problematic questions"
    inputs:
      - name: role
        type: string
        description: "Role being interviewed for"
      - name: skills
        type: string[]
        description: "Key skills to assess"
      - name: level
        type: string
        optional: true
        description: "Seniority level"
    outputs:
      - name: questions
        type: InterviewQuestions
        description: "Categorized interview questions"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  hr.performanceReviewDraft:
    type: utility
    description: "Structures performance review from achievements and feedback into formal review format"
    path: "performance-review-draft"
    domain_rules:
      - id: review_sections
        description: "Must include achievements, areas for growth, goals, rating"
      - id: constructive_framing
        description: "Must frame feedback constructively"
    inputs:
      - name: achievements
        type: string[]
        description: "Key achievements in review period"
      - name: feedback
        type: string[]
        description: "Feedback points to address"
      - name: period
        type: string
        description: "Review period (Q1, annual, etc.)"
    outputs:
      - name: review
        type: PerformanceReview
        description: "Structured performance review"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  hr.onboardingChecklist:
    type: utility
    description: "Generates role-specific onboarding checklists with tasks, owners, and timelines"
    path: "onboarding-checklist"
    domain_rules:
      - id: checklist_structure
        description: "Must organize by day/week with clear owners"
      - id: completeness
        description: "Must cover IT, HR, team, and role-specific items"
    inputs:
      - name: role
        type: string
        description: "New hire's role"
      - name: department
        type: string
        description: "Department"
      - name: startDate
        type: string
        description: "Start date"
    outputs:
      - name: checklist
        type: OnboardingChecklist
        description: "Onboarding checklist with timeline"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  hr.compensationBand:
    type: utility
    description: "Structures compensation data into salary bands with percentiles and benchmarks"
    path: "compensation-band"
    domain_rules:
      - id: band_structure
        description: "Must define min, mid, max with percentiles"
      - id: market_context
        description: "Must include market comparison context"
    inputs:
      - name: role
        type: string
        description: "Role title"
      - name: marketData
        type: object[]
        description: "Market compensation data points"
      - name: location
        type: string
        optional: true
        description: "Geographic location"
    outputs:
      - name: band
        type: CompensationBand
        description: "Structured compensation band"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  hr.surveyAnalyze:
    type: utility
    description: "Analyzes employee survey responses to extract themes, sentiment, and action items"
    path: "survey-analyze"
    domain_rules:
      - id: theme_extraction
        description: "Must identify key themes from responses"
      - id: sentiment_analysis
        description: "Must assess overall and per-question sentiment"
      - id: actionability
        description: "Must suggest action items"
    inputs:
      - name: responses
        type: object[]
        description: "Survey responses"
      - name: questions
        type: string[]
        description: "Survey questions"
    outputs:
      - name: analysis
        type: SurveyAnalysis
        description: "Survey analysis with themes and actions"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  hr.orgChartFormat:
    type: utility
    description: "Formats organizational hierarchy data into structured org chart representation"
    path: "org-chart-format"
    domain_rules:
      - id: hierarchy_structure
        description: "Must represent reporting relationships clearly"
      - id: metadata
        description: "Must include role titles and departments"
    inputs:
      - name: employees
        type: object[]
        description: "Employee data with manager relationships"
    outputs:
      - name: orgChart
        type: OrgChart
        description: "Structured org chart"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  hr.offerLetterDraft:
    type: utility
    description: "Generates offer letter content from compensation and role details"
    path: "offer-letter-draft"
    domain_rules:
      - id: letter_structure
        description: "Must include position, compensation, benefits, start date"
      - id: legal_elements
        description: "Must include at-will statement and contingencies"
    inputs:
      - name: candidate
        type: object
        description: "Candidate name and details"
      - name: offer
        type: object
        description: "Offer details (salary, equity, benefits)"
      - name: role
        type: object
        description: "Role details"
    outputs:
      - name: letter
        type: OfferLetter
        description: "Offer letter content"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  hr.exitInterviewSummarize:
    type: utility
    description: "Summarizes exit interview responses into themes and retention insights"
    path: "exit-interview-summarize"
    domain_rules:
      - id: theme_extraction
        description: "Must extract departure reasons and themes"
      - id: retention_insights
        description: "Must suggest retention improvements"
    inputs:
      - name: responses
        type: object
        description: "Exit interview responses"
    outputs:
      - name: summary
        type: ExitInterviewSummary
        description: "Summarized insights"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  hr.policyDocFormat:
    type: utility
    description: "Formats HR policy content into standardized policy document structure"
    path: "policy-doc-format"
    domain_rules:
      - id: policy_structure
        description: "Must include purpose, scope, policy statement, procedures"
      - id: metadata
        description: "Must include effective date, owner, review date"
    inputs:
      - name: policyContent
        type: string
        description: "Raw policy content"
      - name: policyType
        type: string
        description: "Type of policy (PTO, remote work, etc.)"
    outputs:
      - name: policy
        type: PolicyDocument
        description: "Formatted policy document"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # J) Legal & Contracts (8 tools)
  # ---------------------------------------------------------------------------
  legal.contractClauseScan:
    type: utility
    description: "Scans contract text to identify and categorize key clauses (termination, liability, IP, etc.)"
    path: "contract-clause-scan"
    domain_rules:
      - id: clause_detection
        description: "Must detect common clause types"
      - id: location_reporting
        description: "Must report clause locations in document"
    inputs:
      - name: contractText
        type: string
        description: "Contract text to analyze"
    outputs:
      - name: clauses
        type: ContractClauses
        description: "Identified clauses by category"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  legal.ndaTemplateDraft:
    type: utility
    description: "Generates NDA template with customizable terms for mutual or unilateral agreements"
    path: "nda-template-draft"
    domain_rules:
      - id: nda_structure
        description: "Must include definition, obligations, term, exclusions"
      - id: type_support
        description: "Must support mutual and unilateral types"
    inputs:
      - name: type
        type: "'mutual' | 'unilateral'"
        description: "NDA type"
      - name: disclosingParty
        type: string
        description: "Disclosing party name"
      - name: receivingParty
        type: string
        description: "Receiving party name"
      - name: term
        type: number
        optional: true
        description: "Term in years"
    outputs:
      - name: nda
        type: NDATemplate
        description: "NDA template content"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  legal.tosReadability:
    type: utility
    description: "Analyzes Terms of Service for readability, complexity, and consumer-friendliness"
    path: "tos-readability"
    domain_rules:
      - id: readability_scoring
        description: "Must calculate readability metrics (Flesch, etc.)"
      - id: complexity_analysis
        description: "Must identify complex or problematic sections"
    inputs:
      - name: tosText
        type: string
        description: "Terms of Service text"
    outputs:
      - name: analysis
        type: TOSAnalysis
        description: "Readability analysis with scores"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  legal.riskClauseHighlight:
    type: utility
    description: "Identifies and highlights potentially risky clauses in contracts"
    path: "risk-clause-highlight"
    domain_rules:
      - id: risk_detection
        description: "Must identify liability, indemnification, auto-renewal risks"
      - id: severity_rating
        description: "Must rate risk severity"
    inputs:
      - name: contractText
        type: string
        description: "Contract text to analyze"
    outputs:
      - name: risks
        type: ContractRisks
        description: "Identified risks with severity"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  legal.invoiceTermsExtract:
    type: utility
    description: "Extracts payment terms, due dates, and late fees from invoice text"
    path: "invoice-terms-extract"
    domain_rules:
      - id: term_extraction
        description: "Must extract net days, due date, late fee terms"
      - id: normalization
        description: "Must normalize to standard format"
    inputs:
      - name: invoiceText
        type: string
        description: "Invoice text or terms section"
    outputs:
      - name: terms
        type: PaymentTerms
        description: "Extracted payment terms"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  legal.gdprDataMap:
    type: utility
    description: "Maps data processing activities to GDPR requirements and legal bases"
    path: "gdpr-data-map"
    domain_rules:
      - id: activity_mapping
        description: "Must map each activity to legal basis"
      - id: requirement_check
        description: "Must check against GDPR requirements"
    inputs:
      - name: activities
        type: object[]
        description: "Data processing activities"
    outputs:
      - name: map
        type: GDPRDataMap
        description: "GDPR compliance mapping"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  legal.copyrightNotice:
    type: utility
    description: "Generates appropriate copyright notices for different content types and jurisdictions"
    path: "copyright-notice"
    domain_rules:
      - id: format_rules
        description: "Must follow jurisdiction-specific formats"
      - id: completeness
        description: "Must include year, owner, rights statement"
    inputs:
      - name: owner
        type: string
        description: "Copyright owner name"
      - name: year
        type: number
        description: "Copyright year"
      - name: contentType
        type: string
        description: "Type of content (software, text, media)"
    outputs:
      - name: notice
        type: CopyrightNotice
        description: "Formatted copyright notice"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  legal.trademarkCheck:
    type: utility
    description: "Checks proposed names against common trademark patterns and suggests conflicts"
    path: "trademark-check"
    domain_rules:
      - id: similarity_check
        description: "Must check phonetic and visual similarity"
      - id: class_awareness
        description: "Must consider trademark classes"
    inputs:
      - name: proposedName
        type: string
        description: "Proposed name to check"
      - name: industry
        type: string
        description: "Industry/class for the mark"
    outputs:
      - name: check
        type: TrademarkCheck
        description: "Potential conflicts and recommendations"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # K) Finance & Accounting (8 tools)
  # ---------------------------------------------------------------------------
  finance.expenseCategoriize:
    type: utility
    description: "Categorizes expenses into accounting categories based on description and amount"
    path: "expense-categorize"
    domain_rules:
      - id: category_assignment
        description: "Must assign to standard accounting categories"
      - id: confidence_score
        description: "Must provide confidence for each assignment"
    inputs:
      - name: expenses
        type: object[]
        description: "Expense entries with description and amount"
    outputs:
      - name: categorized
        type: CategorizedExpenses
        description: "Categorized expenses"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  finance.invoiceDataExtract:
    type: utility
    description: "Extracts structured data from invoice text including vendor, line items, totals"
    path: "invoice-data-extract"
    domain_rules:
      - id: field_extraction
        description: "Must extract vendor, date, items, amounts, tax, total"
      - id: validation
        description: "Must validate totals match line items"
    inputs:
      - name: invoiceText
        type: string
        description: "Invoice text content"
    outputs:
      - name: invoice
        type: ExtractedInvoice
        description: "Structured invoice data"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  finance.budgetVariance:
    type: utility
    description: "Calculates budget vs actual variance with percentage and trend analysis"
    path: "budget-variance"
    domain_rules:
      - id: variance_calculation
        description: "Must calculate absolute and percentage variance"
      - id: trend_identification
        description: "Must identify favorable/unfavorable trends"
    inputs:
      - name: budget
        type: object[]
        description: "Budget line items"
      - name: actual
        type: object[]
        description: "Actual spending"
    outputs:
      - name: variance
        type: BudgetVariance
        description: "Variance analysis"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  finance.cashFlowProject:
    type: utility
    description: "Projects cash flow based on receivables, payables, and recurring items"
    path: "cash-flow-project"
    domain_rules:
      - id: projection_logic
        description: "Must project based on timing of ins and outs"
      - id: runway_calculation
        description: "Must calculate runway at current burn"
    inputs:
      - name: currentCash
        type: number
        description: "Current cash balance"
      - name: receivables
        type: object[]
        description: "Expected receivables with dates"
      - name: payables
        type: object[]
        description: "Expected payables with dates"
    outputs:
      - name: projection
        type: CashFlowProjection
        description: "Cash flow projection"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  finance.revenueBreakdown:
    type: utility
    description: "Breaks down revenue by segment, product, or period with growth rates"
    path: "revenue-breakdown"
    domain_rules:
      - id: segmentation
        description: "Must segment by provided dimension"
      - id: growth_calculation
        description: "Must calculate period-over-period growth"
    inputs:
      - name: revenue
        type: object[]
        description: "Revenue data with segments and periods"
      - name: dimension
        type: "'product' | 'segment' | 'region' | 'period'"
        description: "Breakdown dimension"
    outputs:
      - name: breakdown
        type: RevenueBreakdown
        description: "Revenue breakdown with analysis"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  finance.ratioAnalysis:
    type: utility
    description: "Calculates key financial ratios from balance sheet and income statement data"
    path: "ratio-analysis"
    domain_rules:
      - id: ratio_calculation
        description: "Must calculate liquidity, profitability, leverage ratios"
      - id: interpretation
        description: "Must provide ratio interpretations"
    inputs:
      - name: financials
        type: object
        description: "Financial statement data"
    outputs:
      - name: ratios
        type: FinancialRatios
        description: "Calculated ratios with interpretation"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  finance.taxDeductionScan:
    type: utility
    description: "Scans expense data for potential tax deductions by category"
    path: "tax-deduction-scan"
    domain_rules:
      - id: deduction_rules
        description: "Must apply category-specific deduction rules"
      - id: documentation
        description: "Must note documentation requirements"
    inputs:
      - name: expenses
        type: object[]
        description: "Expense records"
      - name: entityType
        type: string
        description: "Business entity type"
    outputs:
      - name: deductions
        type: TaxDeductions
        description: "Potential deductions with requirements"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  finance.reconciliationMatch:
    type: utility
    description: "Matches bank transactions to ledger entries for reconciliation"
    path: "reconciliation-match"
    domain_rules:
      - id: matching_logic
        description: "Must match by amount, date proximity, description"
      - id: confidence_scoring
        description: "Must score match confidence"
    inputs:
      - name: bankTransactions
        type: object[]
        description: "Bank transactions"
      - name: ledgerEntries
        type: object[]
        description: "Ledger entries"
    outputs:
      - name: matches
        type: ReconciliationMatches
        description: "Matched and unmatched items"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # L) Customer Success (7 tools)
  # ---------------------------------------------------------------------------
  cx.feedbackThemes:
    type: utility
    description: "Extracts themes and sentiment from customer feedback text"
    path: "feedback-themes"
    domain_rules:
      - id: theme_extraction
        description: "Must identify recurring themes"
      - id: sentiment_scoring
        description: "Must score sentiment per theme"
    inputs:
      - name: feedback
        type: string[]
        description: "Customer feedback entries"
    outputs:
      - name: themes
        type: FeedbackThemes
        description: "Themes with sentiment and frequency"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  cx.churnRiskScore:
    type: utility
    description: "Scores customer churn risk based on usage, engagement, and support signals"
    path: "churn-risk-score"
    domain_rules:
      - id: signal_weighting
        description: "Must weight usage, engagement, support signals"
      - id: risk_explanation
        description: "Must explain risk factors"
    inputs:
      - name: customer
        type: object
        description: "Customer data with activity metrics"
    outputs:
      - name: risk
        type: ChurnRiskScore
        description: "Risk score with contributing factors"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  cx.npsAnalysis:
    type: utility
    description: "Analyzes NPS survey responses to categorize by promoter/detractor and extract themes"
    path: "nps-analysis"
    domain_rules:
      - id: score_categorization
        description: "Must categorize by score (promoter/passive/detractor)"
      - id: comment_analysis
        description: "Must analyze comments for themes"
    inputs:
      - name: responses
        type: object[]
        description: "NPS responses with score and comment"
    outputs:
      - name: analysis
        type: NPSAnalysis
        description: "NPS breakdown with themes"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  cx.ticketCategorize:
    type: utility
    description: "Categorizes support tickets by type, priority, and product area"
    path: "ticket-categorize"
    domain_rules:
      - id: category_assignment
        description: "Must assign category, priority, product area"
      - id: routing_suggestion
        description: "Must suggest routing based on category"
    inputs:
      - name: ticket
        type: object
        description: "Support ticket with subject and description"
    outputs:
      - name: categorization
        type: TicketCategory
        description: "Ticket categorization"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  cx.responseTemplateSuggest:
    type: utility
    description: "Suggests response templates based on ticket category and customer context"
    path: "response-template-suggest"
    domain_rules:
      - id: template_matching
        description: "Must match templates to ticket type"
      - id: personalization
        description: "Must suggest personalization points"
    inputs:
      - name: ticket
        type: object
        description: "Support ticket"
      - name: customerContext
        type: object
        optional: true
        description: "Customer history and context"
    outputs:
      - name: templates
        type: ResponseTemplates
        description: "Suggested templates ranked by relevance"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  cx.healthScoreCalculate:
    type: utility
    description: "Calculates customer health score from usage, support, payment, and engagement data"
    path: "health-score-calculate"
    domain_rules:
      - id: metric_weighting
        description: "Must weight component metrics"
      - id: trend_analysis
        description: "Must analyze score trend"
    inputs:
      - name: customer
        type: object
        description: "Customer with usage, support, payment data"
    outputs:
      - name: healthScore
        type: HealthScore
        description: "Health score with components"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  cx.renewalForecast:
    type: utility
    description: "Forecasts renewal likelihood based on health score and engagement patterns"
    path: "renewal-forecast"
    domain_rules:
      - id: forecast_model
        description: "Must use health and engagement signals"
      - id: action_suggestions
        description: "Must suggest actions to improve likelihood"
    inputs:
      - name: account
        type: object
        description: "Account with health score and renewal date"
    outputs:
      - name: forecast
        type: RenewalForecast
        description: "Renewal forecast with recommendations"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # M) Education (7 tools)
  # ---------------------------------------------------------------------------
  edu.lessonPlanOutline:
    type: utility
    description: "Generates lesson plan outlines with objectives, activities, and assessments"
    path: "lesson-plan-outline"
    domain_rules:
      - id: plan_structure
        description: "Must include objectives, materials, activities, assessment"
      - id: time_allocation
        description: "Must allocate time for each section"
    inputs:
      - name: topic
        type: string
        description: "Lesson topic"
      - name: duration
        type: number
        description: "Lesson duration in minutes"
      - name: gradeLevel
        type: string
        description: "Target grade level"
    outputs:
      - name: lessonPlan
        type: LessonPlan
        description: "Structured lesson plan"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  edu.quizGenerate:
    type: utility
    description: "Generates quiz questions from content with answer options and explanations"
    path: "quiz-generate"
    domain_rules:
      - id: question_variety
        description: "Must generate varied question types"
      - id: answer_quality
        description: "Must include distractors and explanations"
    inputs:
      - name: content
        type: string
        description: "Source content for questions"
      - name: count
        type: number
        description: "Number of questions"
      - name: difficulty
        type: "'easy' | 'medium' | 'hard'"
        optional: true
        description: "Question difficulty"
    outputs:
      - name: quiz
        type: Quiz
        description: "Generated quiz with answers"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  edu.rubricCreate:
    type: utility
    description: "Creates grading rubrics with criteria, levels, and point values"
    path: "rubric-create"
    domain_rules:
      - id: rubric_structure
        description: "Must define criteria with levels and descriptions"
      - id: scoring_clarity
        description: "Must have clear point allocation"
    inputs:
      - name: assignment
        type: string
        description: "Assignment description"
      - name: criteria
        type: string[]
        description: "Criteria to evaluate"
      - name: totalPoints
        type: number
        description: "Total possible points"
    outputs:
      - name: rubric
        type: GradingRubric
        description: "Complete grading rubric"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  edu.syllabusFormat:
    type: utility
    description: "Formats course syllabus with schedule, policies, and learning outcomes"
    path: "syllabus-format"
    domain_rules:
      - id: syllabus_sections
        description: "Must include all standard syllabus sections"
      - id: policy_completeness
        description: "Must include grading, attendance, academic integrity policies"
    inputs:
      - name: courseInfo
        type: object
        description: "Course details"
      - name: schedule
        type: object[]
        description: "Weekly schedule"
      - name: policies
        type: object
        optional: true
        description: "Course policies"
    outputs:
      - name: syllabus
        type: Syllabus
        description: "Formatted syllabus"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  edu.progressReportDraft:
    type: utility
    description: "Drafts student progress reports from grades and observation notes"
    path: "progress-report-draft"
    domain_rules:
      - id: report_structure
        description: "Must include academic progress, behavior, recommendations"
      - id: constructive_tone
        description: "Must be constructive and growth-oriented"
    inputs:
      - name: student
        type: object
        description: "Student info and grades"
      - name: observations
        type: string[]
        description: "Teacher observations"
    outputs:
      - name: report
        type: ProgressReport
        description: "Progress report content"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  edu.learningObjectiveWrite:
    type: utility
    description: "Writes measurable learning objectives using Bloom's taxonomy verbs"
    path: "learning-objective-write"
    domain_rules:
      - id: blooms_taxonomy
        description: "Must use appropriate Bloom's taxonomy level verbs"
      - id: measurability
        description: "Must be specific and measurable"
    inputs:
      - name: topic
        type: string
        description: "Topic or skill"
      - name: level
        type: "'remember' | 'understand' | 'apply' | 'analyze' | 'evaluate' | 'create'"
        description: "Bloom's taxonomy level"
    outputs:
      - name: objectives
        type: LearningObjectives
        description: "Learning objectives"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  edu.curriculumMap:
    type: utility
    description: "Maps curriculum standards to learning activities and assessments"
    path: "curriculum-map"
    domain_rules:
      - id: standards_alignment
        description: "Must align activities to standards"
      - id: coverage_tracking
        description: "Must track standards coverage"
    inputs:
      - name: standards
        type: object[]
        description: "Curriculum standards"
      - name: units
        type: object[]
        description: "Course units with activities"
    outputs:
      - name: map
        type: CurriculumMap
        description: "Standards to activities mapping"
        measures: [working_implementation, valid_output_structure, readme_documentation]

  # ---------------------------------------------------------------------------
  # K) Sandbox & Code Execution - Sprites API (11 tools)
  # ---------------------------------------------------------------------------
  sprites.createSprite:
    type: utility
    description: "Creates a new isolated Linux sandbox environment (sprite) with persistent filesystem using the Sprites API"
    path: "sprites-create"
    domain_rules:
      - id: api_integration
        description: |
          Must call Sprites API POST /sprites endpoint:
          - Use fetch with Authorization Bearer header
          - Send name in request body
          - Handle API errors with meaningful messages
      - id: auth_handling
        description: "Must use SPRITES_TOKEN environment variable for authentication"
    inputs:
      - name: name
        type: string
        description: "Unique name for the sprite (must be lowercase alphanumeric with hyphens)"
    outputs:
      - name: sprite
        type: Sprite
        description: "Created sprite with name, status, and metadata"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  sprites.listSprites:
    type: utility
    description: "Lists all sprites in the account with their current status and metadata"
    path: "sprites-list"
    domain_rules:
      - id: api_integration
        description: "Must call Sprites API GET /sprites endpoint"
      - id: auth_handling
        description: "Must use SPRITES_TOKEN environment variable for authentication"
    inputs: []
    outputs:
      - name: sprites
        type: Sprite[]
        description: "Array of sprites with name, status, and metadata"
      - name: count
        type: number
        description: "Total number of sprites"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  sprites.getSprite:
    type: utility
    description: "Retrieves details of a specific sprite by name including status and configuration"
    path: "sprites-get"
    domain_rules:
      - id: api_integration
        description: "Must call Sprites API GET /sprites/{name} endpoint"
      - id: error_handling
        description: "Must handle 404 for non-existent sprites gracefully"
    inputs:
      - name: name
        type: string
        description: "Name of the sprite to retrieve"
    outputs:
      - name: sprite
        type: Sprite
        description: "Sprite details including status and metadata"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  sprites.deleteSprite:
    type: utility
    description: "Deletes a sprite and all its associated data including checkpoints"
    path: "sprites-delete"
    domain_rules:
      - id: api_integration
        description: "Must call Sprites API DELETE /sprites/{name} endpoint"
      - id: confirmation
        description: "Returns success status after deletion"
    inputs:
      - name: name
        type: string
        description: "Name of the sprite to delete"
    outputs:
      - name: deleted
        type: boolean
        description: "Whether the sprite was successfully deleted"
      - name: name
        type: string
        description: "Name of the deleted sprite"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  sprites.execCommand:
    type: utility
    description: "Executes a command inside a sprite and returns the output. Supports stdin input for interactive commands."
    path: "sprites-exec"
    domain_rules:
      - id: api_integration
        description: |
          Must call Sprites API POST /sprites/{name}/exec endpoint:
          - Send cmd and optional stdin in request body
          - Handle command execution timeout
          - Return stdout, stderr, and exit code
      - id: timeout_handling
        description: "Must implement configurable timeout (default 60s)"
    inputs:
      - name: name
        type: string
        description: "Name of the sprite to execute command in"
      - name: cmd
        type: string
        description: "Command to execute (e.g., 'ls -la', 'python script.py')"
      - name: stdin
        type: string
        optional: true
        description: "Optional stdin input to pass to the command"
      - name: timeoutMs
        type: number
        optional: true
        description: "Execution timeout in milliseconds (default: 60000)"
    outputs:
      - name: exitCode
        type: number
        description: "Command exit code (0 for success)"
      - name: stdout
        type: string
        description: "Standard output from the command"
      - name: stderr
        type: string
        description: "Standard error output from the command"
      - name: duration
        type: number
        description: "Execution duration in milliseconds"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  sprites.listSessions:
    type: utility
    description: "Lists active execution sessions for a sprite"
    path: "sprites-sessions"
    domain_rules:
      - id: api_integration
        description: "Must call Sprites API GET /sprites/{name}/exec/sessions endpoint"
    inputs:
      - name: name
        type: string
        description: "Name of the sprite to list sessions for"
    outputs:
      - name: sessions
        type: ExecSession[]
        description: "Array of active execution sessions"
      - name: count
        type: number
        description: "Total number of active sessions"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  sprites.createCheckpoint:
    type: utility
    description: "Creates a point-in-time snapshot (checkpoint) of a sprite's filesystem state for later restoration"
    path: "sprites-checkpoint-create"
    domain_rules:
      - id: api_integration
        description: "Must call Sprites API POST /sprites/{name}/checkpoints endpoint"
      - id: checkpoint_metadata
        description: "Must return checkpoint ID and creation timestamp"
    inputs:
      - name: name
        type: string
        description: "Name of the sprite to checkpoint"
      - name: checkpointName
        type: string
        optional: true
        description: "Optional human-readable name for the checkpoint"
    outputs:
      - name: checkpoint
        type: Checkpoint
        description: "Created checkpoint with ID and metadata"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  sprites.listCheckpoints:
    type: utility
    description: "Lists all checkpoints for a sprite ordered by creation time"
    path: "sprites-checkpoint-list"
    domain_rules:
      - id: api_integration
        description: "Must call Sprites API GET /sprites/{name}/checkpoints endpoint"
    inputs:
      - name: name
        type: string
        description: "Name of the sprite to list checkpoints for"
    outputs:
      - name: checkpoints
        type: Checkpoint[]
        description: "Array of checkpoints with IDs and metadata"
      - name: count
        type: number
        description: "Total number of checkpoints"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  sprites.restoreCheckpoint:
    type: utility
    description: "Restores a sprite to a previous checkpoint state, reverting all filesystem changes since that checkpoint"
    path: "sprites-checkpoint-restore"
    domain_rules:
      - id: api_integration
        description: "Must call Sprites API POST /sprites/{name}/checkpoints/{id}/restore endpoint"
      - id: state_verification
        description: "Must verify restoration completed successfully"
    inputs:
      - name: name
        type: string
        description: "Name of the sprite to restore"
      - name: checkpointId
        type: string
        description: "ID of the checkpoint to restore to"
    outputs:
      - name: restored
        type: boolean
        description: "Whether the restoration was successful"
      - name: checkpointId
        type: string
        description: "ID of the restored checkpoint"
      - name: sprite
        type: Sprite
        description: "Sprite status after restoration"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  sprites.getPolicy:
    type: utility
    description: "Retrieves the current network policy for a sprite including allowed domains and filtering rules"
    path: "sprites-policy-get"
    domain_rules:
      - id: api_integration
        description: "Must call Sprites API GET /sprites/{name}/policies endpoint"
    inputs:
      - name: name
        type: string
        description: "Name of the sprite to get policy for"
    outputs:
      - name: policy
        type: NetworkPolicy
        description: "Current network policy with allowed domains and rules"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  sprites.setPolicy:
    type: utility
    description: "Updates the network policy for a sprite to control outbound network access with DNS-based filtering"
    path: "sprites-policy-set"
    domain_rules:
      - id: api_integration
        description: "Must call Sprites API POST /sprites/{name}/policies endpoint"
      - id: policy_validation
        description: "Must validate policy format before sending"
    inputs:
      - name: name
        type: string
        description: "Name of the sprite to update policy for"
      - name: mode
        type: "'allow' | 'deny'"
        description: "Policy mode - 'allow' blocks all except listed, 'deny' allows all except listed"
      - name: domains
        type: string[]
        description: "List of domains to allow or deny based on mode"
    outputs:
      - name: policy
        type: NetworkPolicy
        description: "Updated network policy"
      - name: applied
        type: boolean
        description: "Whether the policy was successfully applied"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  # ---------------------------------------------------------------------------
  # M) Code Execution - Unsandbox (4 tools)
  # ---------------------------------------------------------------------------
  unsandbox.executeCodeAsync:
    type: utility
    description: "Execute code asynchronously in a secure sandbox. Returns a job_id immediately. Use getJob to check status and retrieve results. Supports 42+ languages including Python, JavaScript, TypeScript, Go, Rust, C, C++, Java, Ruby, and more."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /execute/async endpoint"
      - id: language_support
        description: |
          Must support these languages: python, javascript, typescript, ruby, perl, php, lua, bash, r,
          elixir, erlang, tcl, scheme, powershell, clojure, commonlisp, crystal, groovy, deno, awk, raku,
          c, cpp, go, rust, java, kotlin, cobol, fortran, d, zig, nim, v, objc, dart, julia, haskell,
          ocaml, fsharp, csharp, prolog, forth
      - id: network_modes
        description: "Must support 'zerotrust' (default, blocks all network) and 'semitrusted' (allows outbound)"
      - id: input_files
        description: "Must support optional input_files array with filename and base64 content"
    inputs:
      - name: language
        type: string
        description: "Programming language to execute (e.g., 'python', 'javascript', 'go', 'rust')"
      - name: code
        type: string
        description: "The source code to execute"
      - name: input_files
        type: InputFile[]
        optional: true
        description: "Optional array of input files to make available in /tmp/input/"
      - name: network_mode
        type: "'zerotrust' | 'semitrusted'"
        optional: true
        description: "Network isolation mode. 'zerotrust' (default) blocks all network. 'semitrusted' allows outbound."
      - name: ttl
        type: number
        optional: true
        description: "Execution timeout in seconds (1-900). Default: 60."
      - name: return_artifact
        type: boolean
        optional: true
        description: "For compiled languages, return the compiled binary"
      - name: return_wasm_artifact
        type: boolean
        optional: true
        description: "Compile to WebAssembly. Supported for C, C++, Rust, Zig, Go."
    outputs:
      - name: job_id
        type: string
        description: "Job ID to use with getJob to retrieve results"
      - name: status
        type: string
        description: "Initial job status (typically 'queued' or 'running')"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  unsandbox.getJob:
    type: utility
    description: "Get the status and results of an async code execution job. Poll this endpoint until status is 'completed' or 'failed'."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /jobs/{job_id} endpoint"
      - id: status_handling
        description: "Must handle all status values: queued, running, completed, failed"
    inputs:
      - name: job_id
        type: string
        description: "The job ID returned from executeCodeAsync"
    outputs:
      - name: job_id
        type: string
        description: "The job ID"
      - name: status
        type: string
        description: "Job status: 'queued', 'running', 'completed', or 'failed'"
      - name: stdout
        type: string
        optional: true
        description: "Standard output from execution (when completed)"
      - name: stderr
        type: string
        optional: true
        description: "Standard error from execution (when completed)"
      - name: exit_code
        type: number
        optional: true
        description: "Exit code from execution (when completed)"
      - name: duration_ms
        type: number
        optional: true
        description: "Execution duration in milliseconds (when completed)"
      - name: error
        type: string
        optional: true
        description: "Error message (when failed)"
      - name: artifact
        type: string
        optional: true
        description: "Base64-encoded compiled binary (if return_artifact was true)"
      - name: wasm_artifact
        type: string
        optional: true
        description: "Base64-encoded WebAssembly binary (if return_wasm_artifact was true)"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  unsandbox.execute:
    type: utility
    description: "Execute code synchronously in a secure sandbox. Blocks until execution completes and returns results directly. Best for quick scripts under 60 seconds."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /execute endpoint (sync)"
      - id: timeout_handling
        description: "Must handle execution timeout gracefully"
    inputs:
      - name: language
        type: string
        description: "Programming language to execute"
      - name: code
        type: string
        description: "The source code to execute"
      - name: input_files
        type: InputFile[]
        optional: true
        description: "Optional array of input files to make available in /tmp/input/"
      - name: network_mode
        type: "'zerotrust' | 'semitrusted'"
        optional: true
        description: "Network isolation mode. Default: 'zerotrust'"
      - name: ttl
        type: number
        optional: true
        description: "Execution timeout in seconds (1-900). Default: 60."
    outputs:
      - name: stdout
        type: string
        description: "Standard output from execution"
      - name: stderr
        type: string
        description: "Standard error from execution"
      - name: exit_code
        type: number
        description: "Exit code from execution"
      - name: duration_ms
        type: number
        description: "Execution duration in milliseconds"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  unsandbox.run:
    type: utility
    description: "Execute code with automatic language detection from shebang. Send raw code with a shebang line (e.g., #!/usr/bin/env python) and the language is auto-detected."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /run endpoint with text/plain content type"
      - id: shebang_detection
        description: "Language is auto-detected from shebang line in code"
    inputs:
      - name: code
        type: string
        description: "The source code with shebang line (e.g., #!/usr/bin/env python)"
      - name: network_mode
        type: "'zerotrust' | 'semitrusted'"
        optional: true
        description: "Network isolation mode. Default: 'zerotrust'"
      - name: ttl
        type: number
        optional: true
        description: "Execution timeout in seconds (1-900). Default: 60."
    outputs:
      - name: stdout
        type: string
        description: "Standard output from execution"
      - name: stderr
        type: string
        description: "Standard error from execution"
      - name: exit_code
        type: number
        description: "Exit code from execution"
      - name: detected_language
        type: string
        description: "Language detected from shebang"
      - name: duration_ms
        type: number
        description: "Execution duration in milliseconds"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  unsandbox.runAsync:
    type: utility
    description: "Execute code asynchronously with automatic language detection from shebang. Returns a job_id immediately. Use getJob to check status and retrieve results."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /run/async endpoint with text/plain content type"
      - id: shebang_detection
        description: "Language is auto-detected from shebang line in code"
    inputs:
      - name: code
        type: string
        description: "The source code with shebang line (e.g., #!/usr/bin/env python)"
      - name: network_mode
        type: "'zerotrust' | 'semitrusted'"
        optional: true
        description: "Network isolation mode. Default: 'zerotrust'"
      - name: ttl
        type: number
        optional: true
        description: "Execution timeout in seconds (1-900). Default: 60."
    outputs:
      - name: job_id
        type: string
        description: "Job ID to use with getJob to retrieve results"
      - name: status
        type: string
        description: "Initial job status"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  unsandbox.listJobs:
    type: utility
    description: "List all active (pending or running) code execution jobs. Returns an array of job objects with their current status."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /jobs endpoint"
    inputs: []
    outputs:
      - name: jobs
        type: Job[]
        description: "Array of active jobs with id, status, language, and createdAt"
      - name: count
        type: number
        description: "Number of active jobs"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  unsandbox.deleteJob:
    type: utility
    description: "Cancel a pending or running code execution job. The job will be terminated and resources freed."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API DELETE /jobs/{id} endpoint"
      - id: status_validation
        description: "Should handle cases where job is already completed or not found"
    inputs:
      - name: job_id
        type: string
        description: "The job ID to cancel"
    outputs:
      - name: deleted
        type: boolean
        description: "Whether the job was successfully cancelled"
      - name: job_id
        type: string
        description: "The cancelled job ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance, readme_documentation]

  # ---------------------------------------------------------------------------
  # N) Languages (2 tools)
  # ---------------------------------------------------------------------------
  unsandbox.getLanguages:
    type: utility
    description: "Get list of all supported programming languages with metadata including extensions, version, and capabilities."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /languages endpoint"
    inputs: []
    outputs:
      - name: languages
        type: Language[]
        description: "Array of supported languages with id, name, version, extensions, and capabilities"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.getShells:
    type: utility
    description: "Get list of available shell interpreters (bash, zsh, etc.) with their versions and capabilities."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /shells endpoint"
    inputs: []
    outputs:
      - name: shells
        type: Shell[]
        description: "Array of available shells with id, name, version, and path"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ---------------------------------------------------------------------------
  # O) Sessions (11 tools)
  # ---------------------------------------------------------------------------
  unsandbox.createSession:
    type: utility
    description: "Create a new persistent session with configurable language, resources, and networking. Sessions maintain state across executions."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /sessions endpoint"
    inputs:
      - name: language
        type: string
        description: "Programming language for the session"
      - name: network_mode
        type: "'zerotrust' | 'semitrusted'"
        optional: true
        description: "Network isolation mode. Default: 'zerotrust'"
      - name: vcpu
        type: number
        optional: true
        description: "Number of virtual CPUs (0.25-8). Default: 1"
      - name: memory
        type: number
        optional: true
        description: "Memory in MB (256-8192). Default: 512"
      - name: ttl
        type: number
        optional: true
        description: "Session timeout in seconds. Default: 3600"
      - name: env
        type: "Record<string, string>"
        optional: true
        description: "Environment variables for the session"
    outputs:
      - name: session_id
        type: string
        description: "Unique session identifier"
      - name: status
        type: string
        description: "Session status (creating, active, frozen, etc.)"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.getSession:
    type: utility
    description: "Get details of a session including status, resource usage, and configuration."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /sessions/{id} endpoint"
    inputs:
      - name: session_id
        type: string
        description: "The session ID to retrieve"
    outputs:
      - name: session
        type: Session
        description: "Session details including id, status, language, resources, and created_at"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.listSessions:
    type: utility
    description: "List all sessions with optional filtering by status (active, frozen, locked)."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /sessions endpoint"
    inputs:
      - name: status
        type: string
        optional: true
        description: "Filter by status: active, frozen, locked"
    outputs:
      - name: sessions
        type: Session[]
        description: "Array of sessions matching the filter"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.executeInSession:
    type: utility
    description: "Execute code in an existing session. State and files persist between executions."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /sessions/{id}/execute endpoint"
    inputs:
      - name: session_id
        type: string
        description: "The session ID to execute in"
      - name: code
        type: string
        description: "Code to execute"
      - name: timeout
        type: number
        optional: true
        description: "Execution timeout in seconds"
    outputs:
      - name: stdout
        type: string
        description: "Standard output from execution"
      - name: stderr
        type: string
        description: "Standard error from execution"
      - name: exit_code
        type: number
        description: "Process exit code"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.freezeSession:
    type: utility
    description: "Freeze a session to pause execution and reduce resource usage while preserving state."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /sessions/{id}/freeze endpoint"
    inputs:
      - name: session_id
        type: string
        description: "The session ID to freeze"
    outputs:
      - name: success
        type: boolean
        description: "Whether the freeze operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.unfreezeSession:
    type: utility
    description: "Unfreeze a frozen session to resume execution."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /sessions/{id}/unfreeze endpoint"
    inputs:
      - name: session_id
        type: string
        description: "The session ID to unfreeze"
    outputs:
      - name: success
        type: boolean
        description: "Whether the unfreeze operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.lockSession:
    type: utility
    description: "Lock a session to prevent modifications or deletion."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /sessions/{id}/lock endpoint"
    inputs:
      - name: session_id
        type: string
        description: "The session ID to lock"
    outputs:
      - name: success
        type: boolean
        description: "Whether the lock operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.unlockSession:
    type: utility
    description: "Unlock a locked session to allow modifications."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /sessions/{id}/unlock endpoint"
    inputs:
      - name: session_id
        type: string
        description: "The session ID to unlock"
    outputs:
      - name: success
        type: boolean
        description: "Whether the unlock operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.createSessionSnapshot:
    type: utility
    description: "Create a snapshot of the current session state for backup or cloning."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /sessions/{id}/snapshot endpoint"
    inputs:
      - name: session_id
        type: string
        description: "The session ID to snapshot"
      - name: name
        type: string
        optional: true
        description: "Name for the snapshot"
    outputs:
      - name: snapshot_id
        type: string
        description: "ID of the created snapshot"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.restoreSession:
    type: utility
    description: "Restore a session from a snapshot."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /sessions/{id}/restore endpoint"
    inputs:
      - name: session_id
        type: string
        description: "The session ID to restore"
      - name: snapshot_id
        type: string
        description: "The snapshot ID to restore from"
    outputs:
      - name: success
        type: boolean
        description: "Whether the restore operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.deleteSession:
    type: utility
    description: "Delete a session and release all associated resources."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API DELETE /sessions/{id} endpoint"
    inputs:
      - name: session_id
        type: string
        description: "The session ID to delete"
    outputs:
      - name: deleted
        type: boolean
        description: "Whether the deletion succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ---------------------------------------------------------------------------
  # P) Services (15 tools)
  # ---------------------------------------------------------------------------
  unsandbox.createService:
    type: utility
    description: "Create a long-running service with persistent state, networking, and auto-restart capabilities."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /services endpoint"
    inputs:
      - name: language
        type: string
        description: "Programming language for the service"
      - name: code
        type: string
        description: "Service code to run"
      - name: network_mode
        type: "'zerotrust' | 'semitrusted'"
        optional: true
        description: "Network isolation mode"
      - name: port
        type: number
        optional: true
        description: "Port to expose"
      - name: env
        type: "Record<string, string>"
        optional: true
        description: "Environment variables"
    outputs:
      - name: service_id
        type: string
        description: "Unique service identifier"
      - name: url
        type: string
        description: "Public URL for the service"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.getService:
    type: utility
    description: "Get details of a service including status, endpoints, and resource usage."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /services/{id} endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID to retrieve"
    outputs:
      - name: service
        type: Service
        description: "Service details including id, status, url, and resources"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.listServices:
    type: utility
    description: "List all services with optional filtering by status."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /services endpoint"
    inputs:
      - name: status
        type: string
        optional: true
        description: "Filter by status"
    outputs:
      - name: services
        type: Service[]
        description: "Array of services"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.executeInService:
    type: utility
    description: "Execute a command or code snippet in a running service."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /services/{id}/execute endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID to execute in"
      - name: code
        type: string
        description: "Code to execute"
    outputs:
      - name: stdout
        type: string
        description: "Standard output"
      - name: stderr
        type: string
        description: "Standard error"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.freezeService:
    type: utility
    description: "Freeze a service to pause execution while preserving state."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /services/{id}/freeze endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID to freeze"
    outputs:
      - name: success
        type: boolean
        description: "Whether the freeze operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.unfreezeService:
    type: utility
    description: "Unfreeze a frozen service to resume execution."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /services/{id}/unfreeze endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID to unfreeze"
    outputs:
      - name: success
        type: boolean
        description: "Whether the unfreeze operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.lockService:
    type: utility
    description: "Lock a service to prevent modifications or deletion."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /services/{id}/lock endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID to lock"
    outputs:
      - name: success
        type: boolean
        description: "Whether the lock operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.unlockService:
    type: utility
    description: "Unlock a locked service to allow modifications."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /services/{id}/unlock endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID to unlock"
    outputs:
      - name: success
        type: boolean
        description: "Whether the unlock operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.redeployService:
    type: utility
    description: "Redeploy a service with updated configuration or code."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /services/{id}/redeploy endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID to redeploy"
      - name: code
        type: string
        optional: true
        description: "New code to deploy"
    outputs:
      - name: success
        type: boolean
        description: "Whether the redeploy operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.getServiceLogs:
    type: utility
    description: "Get logs from a service with optional filtering by time range and log level."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /services/{id}/logs endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID to get logs from"
      - name: since
        type: string
        optional: true
        description: "ISO timestamp to start from"
      - name: until
        type: string
        optional: true
        description: "ISO timestamp to end at"
      - name: limit
        type: number
        optional: true
        description: "Maximum number of log entries"
    outputs:
      - name: logs
        type: LogEntry[]
        description: "Array of log entries"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.createServiceSnapshot:
    type: utility
    description: "Create a snapshot of the current service state."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /services/{id}/snapshot endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID to snapshot"
      - name: name
        type: string
        optional: true
        description: "Name for the snapshot"
    outputs:
      - name: snapshot_id
        type: string
        description: "ID of the created snapshot"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.getServiceEnv:
    type: utility
    description: "Get environment variables configured for a service."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /services/{id}/env endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID"
    outputs:
      - name: env
        type: "Record<string, string>"
        description: "Environment variables"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.setServiceEnv:
    type: utility
    description: "Set or update environment variables for a service."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API PUT /services/{id}/env endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID"
      - name: env
        type: "Record<string, string>"
        description: "Environment variables to set"
    outputs:
      - name: success
        type: boolean
        description: "Whether the operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.deleteServiceEnv:
    type: utility
    description: "Delete an environment variable from a service."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API DELETE /services/{id}/env/{key} endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID"
      - name: key
        type: string
        description: "Environment variable key to delete"
    outputs:
      - name: success
        type: boolean
        description: "Whether the deletion succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.deleteService:
    type: utility
    description: "Delete a service and release all associated resources."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API DELETE /services/{id} endpoint"
    inputs:
      - name: service_id
        type: string
        description: "The service ID to delete"
    outputs:
      - name: deleted
        type: boolean
        description: "Whether the deletion succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ---------------------------------------------------------------------------
  # Q) Snapshots (8 tools)
  # ---------------------------------------------------------------------------
  unsandbox.createSnapshot:
    type: utility
    description: "Create a snapshot from any source (session, service, or existing snapshot)."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /snapshots endpoint"
    inputs:
      - name: source_type
        type: "'session' | 'service' | 'snapshot'"
        description: "Type of source to snapshot"
      - name: source_id
        type: string
        description: "ID of the source"
      - name: name
        type: string
        optional: true
        description: "Name for the snapshot"
    outputs:
      - name: snapshot_id
        type: string
        description: "ID of the created snapshot"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.getSnapshot:
    type: utility
    description: "Get details of a snapshot including metadata and creation info."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /snapshots/{id} endpoint"
    inputs:
      - name: snapshot_id
        type: string
        description: "The snapshot ID to retrieve"
    outputs:
      - name: snapshot
        type: Snapshot
        description: "Snapshot details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.listSnapshots:
    type: utility
    description: "List all snapshots with optional filtering by source type."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /snapshots endpoint"
    inputs:
      - name: source_type
        type: string
        optional: true
        description: "Filter by source type"
    outputs:
      - name: snapshots
        type: Snapshot[]
        description: "Array of snapshots"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.lockSnapshot:
    type: utility
    description: "Lock a snapshot to prevent deletion or modification."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /snapshots/{id}/lock endpoint"
    inputs:
      - name: snapshot_id
        type: string
        description: "The snapshot ID to lock"
    outputs:
      - name: success
        type: boolean
        description: "Whether the lock operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.unlockSnapshot:
    type: utility
    description: "Unlock a locked snapshot to allow modifications."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /snapshots/{id}/unlock endpoint"
    inputs:
      - name: snapshot_id
        type: string
        description: "The snapshot ID to unlock"
    outputs:
      - name: success
        type: boolean
        description: "Whether the unlock operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.restoreSnapshot:
    type: utility
    description: "Restore a session or service from a snapshot."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /snapshots/{id}/restore endpoint"
    inputs:
      - name: snapshot_id
        type: string
        description: "The snapshot ID to restore"
      - name: target_type
        type: "'session' | 'service'"
        description: "Type of resource to create"
    outputs:
      - name: id
        type: string
        description: "ID of the restored resource"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.cloneSnapshot:
    type: utility
    description: "Clone a snapshot to create a new independent copy."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /snapshots/{id}/clone endpoint"
    inputs:
      - name: snapshot_id
        type: string
        description: "The snapshot ID to clone"
      - name: name
        type: string
        optional: true
        description: "Name for the cloned snapshot"
    outputs:
      - name: snapshot_id
        type: string
        description: "ID of the cloned snapshot"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.deleteSnapshot:
    type: utility
    description: "Delete a snapshot and free associated storage."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API DELETE /snapshots/{id} endpoint"
    inputs:
      - name: snapshot_id
        type: string
        description: "The snapshot ID to delete"
    outputs:
      - name: deleted
        type: boolean
        description: "Whether the deletion succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ---------------------------------------------------------------------------
  # R) Images (12 tools)
  # ---------------------------------------------------------------------------
  unsandbox.publishImage:
    type: utility
    description: "Publish a snapshot as a reusable image for spawning new sessions or services."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /images endpoint"
    inputs:
      - name: snapshot_id
        type: string
        description: "The snapshot ID to publish"
      - name: name
        type: string
        description: "Name for the image"
      - name: visibility
        type: "'public' | 'private'"
        optional: true
        description: "Image visibility. Default: 'private'"
    outputs:
      - name: image_id
        type: string
        description: "ID of the published image"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.getImage:
    type: utility
    description: "Get details of a published image including metadata and access info."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /images/{id} endpoint"
    inputs:
      - name: image_id
        type: string
        description: "The image ID to retrieve"
    outputs:
      - name: image
        type: Image
        description: "Image details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.listImages:
    type: utility
    description: "List all images with optional filtering by visibility and ownership."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /images endpoint"
    inputs:
      - name: visibility
        type: string
        optional: true
        description: "Filter by visibility: public, private"
      - name: owned
        type: boolean
        optional: true
        description: "Filter to only owned images"
    outputs:
      - name: images
        type: Image[]
        description: "Array of images"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.lockImage:
    type: utility
    description: "Lock an image to prevent modifications or deletion."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /images/{id}/lock endpoint"
    inputs:
      - name: image_id
        type: string
        description: "The image ID to lock"
    outputs:
      - name: success
        type: boolean
        description: "Whether the lock operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.unlockImage:
    type: utility
    description: "Unlock a locked image to allow modifications."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /images/{id}/unlock endpoint"
    inputs:
      - name: image_id
        type: string
        description: "The image ID to unlock"
    outputs:
      - name: success
        type: boolean
        description: "Whether the unlock operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.grantImageAccess:
    type: utility
    description: "Grant access to a private image for specific users or API keys."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /images/{id}/access endpoint"
    inputs:
      - name: image_id
        type: string
        description: "The image ID"
      - name: public_key
        type: string
        description: "Public key to grant access to"
    outputs:
      - name: success
        type: boolean
        description: "Whether the grant operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.revokeImageAccess:
    type: utility
    description: "Revoke access to an image from specific users or API keys."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API DELETE /images/{id}/access/{key} endpoint"
    inputs:
      - name: image_id
        type: string
        description: "The image ID"
      - name: public_key
        type: string
        description: "Public key to revoke access from"
    outputs:
      - name: success
        type: boolean
        description: "Whether the revoke operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.transferImage:
    type: utility
    description: "Transfer ownership of an image to another user."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /images/{id}/transfer endpoint"
    inputs:
      - name: image_id
        type: string
        description: "The image ID to transfer"
      - name: new_owner_key
        type: string
        description: "Public key of the new owner"
    outputs:
      - name: success
        type: boolean
        description: "Whether the transfer succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.setImageVisibility:
    type: utility
    description: "Set image visibility to public or private."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API PUT /images/{id}/visibility endpoint"
    inputs:
      - name: image_id
        type: string
        description: "The image ID"
      - name: visibility
        type: "'public' | 'private'"
        description: "New visibility setting"
    outputs:
      - name: success
        type: boolean
        description: "Whether the operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.spawnFromImage:
    type: utility
    description: "Spawn a new session or service from an image."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API POST /images/{id}/spawn endpoint"
    inputs:
      - name: image_id
        type: string
        description: "The image ID to spawn from"
      - name: type
        type: "'session' | 'service'"
        description: "Type of resource to create"
      - name: network_mode
        type: "'zerotrust' | 'semitrusted'"
        optional: true
        description: "Network isolation mode"
    outputs:
      - name: id
        type: string
        description: "ID of the spawned resource"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.getImageTrustedKeys:
    type: utility
    description: "Get list of API keys that have access to a private image."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /images/{id}/trusted endpoint"
    inputs:
      - name: image_id
        type: string
        description: "The image ID"
    outputs:
      - name: keys
        type: string[]
        description: "Array of public keys with access"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.deleteImage:
    type: utility
    description: "Delete an image and free associated storage."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API DELETE /images/{id} endpoint"
    inputs:
      - name: image_id
        type: string
        description: "The image ID to delete"
    outputs:
      - name: deleted
        type: boolean
        description: "Whether the deletion succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ---------------------------------------------------------------------------
  # S) System (4 tools)
  # ---------------------------------------------------------------------------
  unsandbox.healthCheck:
    type: utility
    description: "Check the health status of the Unsandbox API service."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /health endpoint"
    inputs: []
    outputs:
      - name: status
        type: string
        description: "Health status (healthy, degraded, unhealthy)"
      - name: version
        type: string
        description: "API version"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.getClusterStatus:
    type: utility
    description: "Get status of the execution cluster including node availability and capacity."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /cluster endpoint"
    inputs: []
    outputs:
      - name: nodes
        type: number
        description: "Number of active nodes"
      - name: capacity
        type: object
        description: "Available capacity information"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.getSystemStats:
    type: utility
    description: "Get system statistics including resource utilization and job metrics."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /stats endpoint"
    inputs: []
    outputs:
      - name: jobs_total
        type: number
        description: "Total jobs processed"
      - name: jobs_active
        type: number
        description: "Currently active jobs"
      - name: resource_usage
        type: object
        description: "Resource utilization metrics"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  unsandbox.listPools:
    type: utility
    description: "List available execution pools with their configurations and current status."
    path: "unsandbox"
    domain_rules:
      - id: api_integration
        description: "Must call Unsandbox API GET /pools endpoint"
    inputs: []
    outputs:
      - name: pools
        type: Pool[]
        description: "Array of execution pools"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ---------------------------------------------------------------------------
  # T) exe.dev VM Management (15 tools)
  # ---------------------------------------------------------------------------
  exe.list:
    type: utility
    description: "List all exe.dev virtual machines for the authenticated user. Returns VM names, images, status, and URLs."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev ls --json' command"
      - id: json_parsing
        description: "Must parse JSON output into structured VM list"
    inputs: []
    outputs:
      - name: vms
        type: exe_vm_list
        description: "List of VMs with their details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.create:
    type: utility
    description: "Create a new exe.dev virtual machine. Supports custom images, environment variables, and Shelley prompts."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev new' with appropriate flags"
      - id: option_building
        description: "Must properly format --name, --image, --env, --prompt flags"
    inputs:
      - name: name
        type: string
        optional: true
        description: "VM name (auto-generated if not provided)"
      - name: image
        type: string
        optional: true
        description: "Container image (default: exeuntu)"
      - name: env
        type: object
        optional: true
        description: "Environment variables as key-value pairs"
      - name: prompt
        type: string
        optional: true
        description: "Initial prompt to send to Shelley after creation"
      - name: command
        type: string
        optional: true
        description: "Container command mode: auto, none, or custom command"
    outputs:
      - name: vm
        type: exe_vm
        description: "Created VM details including name and URL"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.delete:
    type: utility
    description: "Delete an exe.dev virtual machine. This permanently removes the VM and its data."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev rm <vmname> --json'"
    inputs:
      - name: name
        type: string
        description: "Name of the VM to delete"
    outputs:
      - name: deleted
        type: boolean
        description: "Whether the VM was successfully deleted"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.restart:
    type: utility
    description: "Restart an exe.dev virtual machine. Useful for applying changes or recovering from issues."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev restart <vmname> --json'"
    inputs:
      - name: name
        type: string
        description: "Name of the VM to restart"
    outputs:
      - name: restarted
        type: boolean
        description: "Whether the VM was successfully restarted"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.exec:
    type: utility
    description: "Execute a command on an exe.dev VM via SSH. Returns stdout, stderr, and exit code."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev ssh <vmname> <command>'"
      - id: output_capture
        description: "Must capture and return stdout, stderr, and exit code"
    inputs:
      - name: vm
        type: string
        description: "Name of the VM to execute on"
      - name: command
        type: string
        description: "Command to execute on the VM"
    outputs:
      - name: result
        type: exe_command_result
        description: "Command execution result with stdout, stderr, exitCode"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.shareShow:
    type: utility
    description: "Show the sharing configuration for an exe.dev VM including public status, port, users, and share links."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev share show <vmname> --json'"
    inputs:
      - name: vm
        type: string
        description: "Name of the VM"
    outputs:
      - name: share
        type: exe_share_info
        description: "Sharing configuration for the VM"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.shareSetPublic:
    type: utility
    description: "Make an exe.dev VM's HTTP proxy publicly accessible without authentication."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev share set-public <vmname>'"
    inputs:
      - name: vm
        type: string
        description: "Name of the VM to make public"
    outputs:
      - name: success
        type: boolean
        description: "Whether the operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.shareSetPrivate:
    type: utility
    description: "Make an exe.dev VM's HTTP proxy private, requiring authentication to access."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev share set-private <vmname>'"
    inputs:
      - name: vm
        type: string
        description: "Name of the VM to make private"
    outputs:
      - name: success
        type: boolean
        description: "Whether the operation succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.sharePort:
    type: utility
    description: "Configure the HTTP proxy port for an exe.dev VM. Traffic to the VM's URL will be forwarded to this port."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev share port <vmname> <port>'"
    inputs:
      - name: vm
        type: string
        description: "Name of the VM"
      - name: port
        type: number
        description: "Port number to proxy to (e.g., 8080)"
    outputs:
      - name: success
        type: boolean
        description: "Whether the port was successfully configured"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.shareAddUser:
    type: utility
    description: "Grant a user access to an exe.dev VM by email. Sends an invitation with optional custom message."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev share add <vmname> <email>'"
    inputs:
      - name: vm
        type: string
        description: "Name of the VM"
      - name: email
        type: string
        description: "Email address of user to invite"
      - name: message
        type: string
        optional: true
        description: "Custom invitation message"
    outputs:
      - name: success
        type: boolean
        description: "Whether the user was successfully added"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.shareRemoveUser:
    type: utility
    description: "Revoke a user's access to an exe.dev VM by email."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev share remove <vmname> <email>'"
    inputs:
      - name: vm
        type: string
        description: "Name of the VM"
      - name: email
        type: string
        description: "Email address of user to remove"
    outputs:
      - name: success
        type: boolean
        description: "Whether the user was successfully removed"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.shareAddLink:
    type: utility
    description: "Generate a shareable link for an exe.dev VM that can be shared with anyone."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev share add-link <vmname> --json'"
    inputs:
      - name: vm
        type: string
        description: "Name of the VM"
    outputs:
      - name: link
        type: exe_share_link
        description: "Generated share link with token and URL"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.shareRemoveLink:
    type: utility
    description: "Revoke a shareable link for an exe.dev VM."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev share remove-link <vmname> <token>'"
    inputs:
      - name: vm
        type: string
        description: "Name of the VM"
      - name: token
        type: string
        description: "Token of the share link to remove"
    outputs:
      - name: success
        type: boolean
        description: "Whether the link was successfully removed"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.whoami:
    type: utility
    description: "Get the current exe.dev user's account information including email and SSH keys."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev whoami --json'"
    inputs: []
    outputs:
      - name: user
        type: exe_user_info
        description: "User account information"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  exe.shelleyInstall:
    type: utility
    description: "Install or upgrade the Shelley agent on an exe.dev VM to the latest version."
    path: "exe-dev"
    domain_rules:
      - id: ssh_execution
        description: "Must execute 'ssh exe.dev shelley install <vmname>'"
    inputs:
      - name: vm
        type: string
        description: "Name of the VM to install Shelley on"
    outputs:
      - name: success
        type: boolean
        description: "Whether Shelley was successfully installed/upgraded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ---------------------------------------------------------------------------
  # N) HLLM - Topology & Agent Tools
  # ---------------------------------------------------------------------------
  hllm.executeTopology:
    type: utility
    description: "Execute a topology with streaming SSE response. Supports topology types: single, sequential, parallel, map-reduce, scatter, debate, reflection, consensus, brainstorm, decomposition, rhetorical-triangle, tree-of-thoughts, react."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API POST /topology/execute endpoint"
      - id: topology_types
        description: "Must support all topology types: single, sequential, parallel, map-reduce, scatter, debate, reflection, consensus, brainstorm, decomposition, rhetorical-triangle, tree-of-thoughts, react"
    inputs:
      - name: topology
        type: string
        description: "Type of topology to execute"
      - name: prompt
        type: string
        description: "The prompt to send to the topology"
      - name: model
        type: string
        optional: true
        description: "Model to use (e.g., 'gpt-4', 'claude-3-opus')"
      - name: systemPrompt
        type: string
        optional: true
        description: "System prompt to set the context"
      - name: temperature
        type: number
        optional: true
        description: "Temperature for response randomness (0-2)"
      - name: maxTokens
        type: number
        optional: true
        description: "Maximum tokens in response"
      - name: tools
        type: string[]
        optional: true
        description: "Tool IDs to make available to the topology"
      - name: sessionId
        type: string
        optional: true
        description: "Session ID to continue a conversation"
    outputs:
      - name: id
        type: string
        description: "Execution ID"
      - name: status
        type: string
        description: "Execution status"
      - name: output
        type: string
        description: "Generated output"
      - name: tokens
        type: object
        description: "Token usage (input, output, total)"
      - name: duration
        type: number
        description: "Execution duration in ms"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.listSessions:
    type: utility
    description: "List all chat sessions for the authenticated user."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /sessions endpoint"
    inputs:
      - name: limit
        type: number
        optional: true
        description: "Maximum number of sessions to return"
      - name: offset
        type: number
        optional: true
        description: "Number of sessions to skip"
    outputs:
      - name: sessions
        type: hllm_session[]
        description: "Array of chat sessions"
      - name: total
        type: number
        description: "Total number of sessions"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.createSession:
    type: utility
    description: "Create a new chat session with optional initial configuration."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API POST /sessions endpoint"
    inputs:
      - name: title
        type: string
        optional: true
        description: "Title for the session"
      - name: systemPrompt
        type: string
        optional: true
        description: "System prompt for the session"
    outputs:
      - name: session
        type: hllm_session
        description: "The created session"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.getSession:
    type: utility
    description: "Get details of a specific chat session including messages."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /sessions/{id} endpoint"
    inputs:
      - name: sessionId
        type: string
        description: "The session ID"
    outputs:
      - name: session
        type: hllm_session
        description: "Session details"
      - name: messages
        type: hllm_message[]
        description: "Messages in the session"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.updateSession:
    type: utility
    description: "Update session properties like title or configuration."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API PATCH /sessions/{id} endpoint"
    inputs:
      - name: sessionId
        type: string
        description: "The session ID"
      - name: title
        type: string
        optional: true
        description: "New title for the session"
      - name: systemPrompt
        type: string
        optional: true
        description: "New system prompt"
    outputs:
      - name: session
        type: hllm_session
        description: "Updated session"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.deleteSession:
    type: utility
    description: "Delete a chat session and all its messages."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API DELETE /sessions/{id} endpoint"
    inputs:
      - name: sessionId
        type: string
        description: "The session ID to delete"
    outputs:
      - name: success
        type: boolean
        description: "Whether deletion was successful"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.addMessage:
    type: utility
    description: "Add a message to a chat session."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API POST /sessions/{id}/messages endpoint"
    inputs:
      - name: sessionId
        type: string
        description: "The session ID"
      - name: role
        type: string
        description: "Message role: user, assistant, or system"
      - name: content
        type: string
        description: "Message content"
    outputs:
      - name: message
        type: hllm_message
        description: "The created message"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.clearMessages:
    type: utility
    description: "Clear all messages from a chat session."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API DELETE /sessions/{id}/messages endpoint"
    inputs:
      - name: sessionId
        type: string
        description: "The session ID"
    outputs:
      - name: success
        type: boolean
        description: "Whether clearing was successful"
      - name: clearedCount
        type: number
        description: "Number of messages cleared"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.listPrompts:
    type: utility
    description: "List all prompts in the prompt library with optional filtering."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /prompts endpoint"
    inputs:
      - name: category
        type: string
        optional: true
        description: "Filter by category"
      - name: search
        type: string
        optional: true
        description: "Search in name and content"
      - name: limit
        type: number
        optional: true
        description: "Maximum number of prompts to return"
      - name: offset
        type: number
        optional: true
        description: "Number of prompts to skip"
    outputs:
      - name: prompts
        type: hllm_prompt[]
        description: "Array of prompts"
      - name: total
        type: number
        description: "Total number of prompts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.createPrompt:
    type: utility
    description: "Create a new prompt in the library."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API POST /prompts endpoint"
    inputs:
      - name: name
        type: string
        description: "Name of the prompt"
      - name: content
        type: string
        description: "The prompt content/template"
      - name: description
        type: string
        optional: true
        description: "Description of what the prompt does"
      - name: category
        type: string
        optional: true
        description: "Category for organization"
      - name: tags
        type: string[]
        optional: true
        description: "Tags for filtering"
    outputs:
      - name: prompt
        type: hllm_prompt
        description: "The created prompt"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.getPrompt:
    type: utility
    description: "Get details of a specific prompt."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /prompts/{id} endpoint"
    inputs:
      - name: promptId
        type: string
        description: "The prompt ID"
    outputs:
      - name: prompt
        type: hllm_prompt
        description: "Prompt details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.updatePrompt:
    type: utility
    description: "Update an existing prompt."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API PATCH /prompts/{id} endpoint"
    inputs:
      - name: promptId
        type: string
        description: "The prompt ID"
      - name: name
        type: string
        optional: true
        description: "New name"
      - name: content
        type: string
        optional: true
        description: "New content"
      - name: description
        type: string
        optional: true
        description: "New description"
      - name: category
        type: string
        optional: true
        description: "New category"
      - name: tags
        type: string[]
        optional: true
        description: "New tags"
    outputs:
      - name: prompt
        type: hllm_prompt
        description: "Updated prompt"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.deletePrompt:
    type: utility
    description: "Delete a prompt from the library."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API DELETE /prompts/{id} endpoint"
    inputs:
      - name: promptId
        type: string
        description: "The prompt ID to delete"
    outputs:
      - name: success
        type: boolean
        description: "Whether deletion was successful"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.incrementPromptUsage:
    type: utility
    description: "Increment the usage count for a prompt."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API POST /prompts/{id}/usage endpoint"
    inputs:
      - name: promptId
        type: string
        description: "The prompt ID"
    outputs:
      - name: usageCount
        type: number
        description: "New usage count"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.getUserProfile:
    type: utility
    description: "Get the current user's profile information."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /user/profile endpoint"
    inputs: []
    outputs:
      - name: profile
        type: hllm_user_profile
        description: "User profile information"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.updateUserProfile:
    type: utility
    description: "Update the current user's profile."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API PATCH /user/profile endpoint"
    inputs:
      - name: name
        type: string
        optional: true
        description: "Display name"
      - name: avatar
        type: string
        optional: true
        description: "Avatar URL"
      - name: preferences
        type: object
        optional: true
        description: "User preferences"
    outputs:
      - name: profile
        type: hllm_user_profile
        description: "Updated profile"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.getUserStats:
    type: utility
    description: "Get usage statistics for the current user."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /user/stats endpoint"
    inputs:
      - name: period
        type: string
        optional: true
        description: "Time period: day, week, month, or all"
    outputs:
      - name: stats
        type: hllm_user_stats
        description: "User statistics"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.listEnvVars:
    type: utility
    description: "List all TPMJS environment variables."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /env-vars endpoint"
    inputs: []
    outputs:
      - name: envVars
        type: hllm_env_var[]
        description: "Array of environment variables"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.setEnvVar:
    type: utility
    description: "Set or update a TPMJS environment variable."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API PUT /env-vars endpoint"
    inputs:
      - name: key
        type: string
        description: "Variable name"
      - name: value
        type: string
        description: "Variable value"
    outputs:
      - name: envVar
        type: hllm_env_var
        description: "The created/updated variable"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.deleteEnvVar:
    type: utility
    description: "Delete a TPMJS environment variable."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API DELETE /env-vars/{key} endpoint"
    inputs:
      - name: key
        type: string
        description: "Variable name to delete"
    outputs:
      - name: success
        type: boolean
        description: "Whether deletion was successful"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.uploadFile:
    type: utility
    description: "Upload a file for use in topologies."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API POST /files endpoint"
    inputs:
      - name: name
        type: string
        description: "File name"
      - name: content
        type: string
        description: "Base64-encoded file content"
      - name: mimeType
        type: string
        optional: true
        description: "MIME type of the file"
    outputs:
      - name: file
        type: hllm_file
        description: "Uploaded file information"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.getFile:
    type: utility
    description: "Get file metadata and download URL."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /files/{id} endpoint"
    inputs:
      - name: fileId
        type: string
        description: "The file ID"
    outputs:
      - name: file
        type: hllm_file
        description: "File information"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.deleteFile:
    type: utility
    description: "Delete an uploaded file."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API DELETE /files/{id} endpoint"
    inputs:
      - name: fileId
        type: string
        description: "The file ID to delete"
    outputs:
      - name: success
        type: boolean
        description: "Whether deletion was successful"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.listModels:
    type: utility
    description: "List all available AI models."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /models endpoint"
    inputs:
      - name: provider
        type: string
        optional: true
        description: "Filter by provider (openai, anthropic, google, etc.)"
    outputs:
      - name: models
        type: hllm_model[]
        description: "Array of available models"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.getExecutionLogs:
    type: utility
    description: "Get execution logs for topology runs."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /logs endpoint"
    inputs:
      - name: sessionId
        type: string
        optional: true
        description: "Filter logs by session ID"
      - name: limit
        type: number
        optional: true
        description: "Maximum number of logs to return"
      - name: offset
        type: number
        optional: true
        description: "Number of logs to skip"
    outputs:
      - name: logs
        type: hllm_execution_log[]
        description: "Array of execution logs"
      - name: total
        type: number
        description: "Total number of logs"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.getAgentMetrics:
    type: utility
    description: "Get agent performance metrics."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /metrics endpoint"
    inputs:
      - name: period
        type: string
        optional: true
        description: "Time period: hour, day, week, or month"
    outputs:
      - name: metrics
        type: hllm_agent_metrics
        description: "Agent metrics"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.listTools:
    type: utility
    description: "List all available TPMJS tools."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /tools endpoint"
    inputs:
      - name: category
        type: string
        optional: true
        description: "Filter by category"
    outputs:
      - name: tools
        type: hllm_tool_info[]
        description: "Array of available tools"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.describeTool:
    type: utility
    description: "Get detailed description of a specific tool."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /tools/{id} endpoint"
    inputs:
      - name: toolId
        type: string
        description: "The tool ID"
    outputs:
      - name: tool
        type: hllm_tool_info
        description: "Tool information"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.executeTool:
    type: utility
    description: "Execute a TPMJS tool directly."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API POST /tools/{id}/execute endpoint"
    inputs:
      - name: toolId
        type: string
        description: "The tool ID to execute"
      - name: parameters
        type: object
        description: "Tool parameters"
    outputs:
      - name: success
        type: boolean
        description: "Whether execution was successful"
      - name: result
        type: any
        description: "Tool execution result"
      - name: duration
        type: number
        description: "Execution duration in ms"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.generatePrompt:
    type: utility
    description: "Generate a prompt using AI assistance."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API POST /prompts/generate endpoint"
    inputs:
      - name: task
        type: string
        description: "Description of what the prompt should accomplish"
      - name: context
        type: string
        optional: true
        description: "Additional context for prompt generation"
      - name: style
        type: string
        optional: true
        description: "Style: concise, detailed, or creative"
    outputs:
      - name: prompt
        type: string
        description: "Generated prompt"
      - name: suggestions
        type: string[]
        optional: true
        description: "Alternative suggestions"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.improvePrompt:
    type: utility
    description: "Improve an existing prompt using AI."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API POST /prompts/improve endpoint"
    inputs:
      - name: prompt
        type: string
        description: "The prompt to improve"
      - name: goal
        type: string
        optional: true
        description: "What improvement to focus on"
    outputs:
      - name: prompt
        type: string
        description: "Improved prompt"
      - name: suggestions
        type: string[]
        optional: true
        description: "Alternative suggestions"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.exportData:
    type: utility
    description: "Export user data including sessions, prompts, and settings."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API POST /export endpoint"
    inputs:
      - name: include
        type: string[]
        optional: true
        description: "What data to include: sessions, prompts, settings, files"
    outputs:
      - name: data
        type: string
        description: "Base64 encoded export data"
      - name: format
        type: string
        description: "Export format"
      - name: exportedAt
        type: string
        description: "Export timestamp"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.importData:
    type: utility
    description: "Import previously exported data."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API POST /import endpoint"
    inputs:
      - name: data
        type: string
        description: "Base64 encoded export data"
      - name: overwrite
        type: boolean
        optional: true
        description: "Whether to overwrite existing data"
    outputs:
      - name: success
        type: boolean
        description: "Whether import was successful"
      - name: imported
        type: object
        description: "Summary of imported items"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.healthCheck:
    type: utility
    description: "Check HLLM API health status."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /health endpoint"
    inputs: []
    outputs:
      - name: status
        type: string
        description: "Health status"
      - name: version
        type: string
        description: "API version"
      - name: uptime
        type: number
        description: "Uptime in seconds"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.getStats:
    type: utility
    description: "Get public HLLM statistics."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /stats endpoint"
    inputs: []
    outputs:
      - name: totalUsers
        type: number
        description: "Total number of users"
      - name: totalExecutions
        type: number
        description: "Total number of executions"
      - name: totalTokens
        type: number
        description: "Total tokens processed"
      - name: uptimePercent
        type: number
        description: "Uptime percentage"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.listApiKeys:
    type: utility
    description: "List all API keys for the authenticated user."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API GET /api-keys endpoint"
    inputs: []
    outputs:
      - name: apiKeys
        type: hllm_api_key[]
        description: "Array of API keys"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.createApiKey:
    type: utility
    description: "Create a new API key."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API POST /api-keys endpoint"
    inputs:
      - name: name
        type: string
        description: "Name for the API key"
    outputs:
      - name: id
        type: string
        description: "Key ID"
      - name: name
        type: string
        description: "Key name"
      - name: key
        type: string
        description: "Full API key (only shown once)"
      - name: createdAt
        type: string
        description: "Creation timestamp"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  hllm.deleteApiKey:
    type: utility
    description: "Delete an API key."
    path: "hllm"
    domain_rules:
      - id: api_integration
        description: "Must call HLLM API DELETE /api-keys/{id} endpoint"
    inputs:
      - name: keyId
        type: string
        description: "The API key ID to delete"
    outputs:
      - name: success
        type: boolean
        description: "Whether deletion was successful"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ---------------------------------------------------------------------------
  # Utility Tools
  # ---------------------------------------------------------------------------
  utility.sleep:
    type: utility
    description: "Pauses execution for a specified duration. Returns a cute message about taking a little nap. Useful for rate limiting, waiting for external processes, or adding delays between operations."
    path: "sleep"
    domain_rules:
      - id: async_sleep
        description: "Must use setTimeout wrapped in a Promise for non-blocking sleep"
      - id: max_duration
        description: "Must enforce a maximum sleep duration of 300 seconds (5 minutes) to prevent abuse"
    inputs:
      - name: seconds
        type: number
        description: "Number of seconds to sleep (max 300)"
      - name: reason
        type: string
        optional: true
        description: "Optional reason for sleeping (for logging purposes)"
    outputs:
      - name: sleptFor
        type: number
        description: "Actual seconds slept"
      - name: message
        type: string
        description: "A cute message about the nap"
        extra_prompt: "Include a playful, cozy message about taking a little rest. Examples: '😴 zzz... had a lovely {duration} second nap!', '💤 *yawn* refreshed after snoozing for {duration}s', '🛏️ ahh, that was a nice little rest...'"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ---------------------------------------------------------------------------
  # Agent Quality Tools
  # ---------------------------------------------------------------------------
  agent.judgeConversation:
    type: utility
    description: "Evaluate an AI conversation across 10 quality metrics to ensure the AI is making real progress and completing user intent. Use this tool FREQUENTLY in agentic loops to verify progress, catch stuck states, and get actionable improvements."
    path: "judge"
    domain_rules:
      - id: metric_evaluation
        description: "Must evaluate all 10 metrics: taskCompletion, accuracy, relevance, clarity, efficiency, userIntentAlignment, actionability, progress, errorHandling, completeness"
      - id: loop_detection
        description: "Must detect conversation loops, repetition patterns, and oscillation"
      - id: tool_analysis
        description: "Must analyze tool call patterns and success/failure rates"
      - id: verdict_generation
        description: "Must return a verdict (pass/retry/fail) with actionable must-dos"
    inputs:
      - name: messages
        type: array
        description: "Array of AI SDK messages with role, content, toolCalls, and toolResults"
      - name: originalUserRequest
        type: string
        optional: true
        description: "The original user request if different from first message"
      - name: context
        type: string
        optional: true
        description: "Additional context about what the conversation should accomplish"
      - name: strictMode
        type: boolean
        optional: true
        description: "If true, requires higher scores to pass (default: false)"
    outputs:
      - name: overallScore
        type: number
        description: "Weighted average score across all metrics (0-10)"
      - name: verdict
        type: string
        description: "pass, retry, or fail"
      - name: verdictReason
        type: string
        description: "Explanation for the verdict"
      - name: metrics
        type: array
        description: "Individual metric evaluations with scores, reasons, mustDos, and suggestions"
      - name: criticalIssues
        type: array
        description: "List of blocking issues that must be addressed"
      - name: mustDos
        type: array
        description: "Critical actions that MUST be taken"
      - name: suggestions
        type: array
        description: "Helpful improvements"
      - name: nextSteps
        type: array
        description: "Recommended next actions"
      - name: loopDetected
        type: boolean
        description: "Whether a conversation loop was detected"
      - name: conversationSummary
        type: string
        description: "Brief summary of the conversation"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

# =============================================================================
# VALIDATORS - Which validators to run against each block
# =============================================================================
validators:
  schema:
    - id: io_schema
      run: "schema.io.v1"

  shape:
    - id: export_shape
      run: "shape.exports.v1"

  domain:
    - id: domain_alignment
      run: "domain.validation.v1"

pipeline:
  name: "default"
  steps:
    - id: schema
      run: "schema.io.v1"
    - id: shape
      run: "shape.exports.v1"
    - id: domain
      run: "domain.validation.v1"