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"

    # -------------------------------------------------------------------------
    # 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]

  # ---------------------------------------------------------------------------
  # 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]

# =============================================================================
# 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"