tpmjs/packages/tools/official/blocks.yml

name: "tpmjs-official-tools"
root: "."

# AI Configuration
ai:
  provider: "openai"
  model: "gpt-4o-mini"

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

    # -------------------------------------------------------------------------
    # E2B Cloud Sandbox entities
    # -------------------------------------------------------------------------
    e2b_sandbox:
      fields: [sandboxId, templateId, status, startedAt, clientId, metadata]
      description: "E2B cloud sandbox instance for AI code execution"

    e2b_sandbox_list:
      fields: [sandboxes, count]
      description: "Collection of E2B sandboxes"

    e2b_exec_result:
      fields: [stdout, stderr, exitCode, results, error, duration]
      description: "Result of code execution in E2B sandbox"

    e2b_file_info:
      fields: [name, path, type, size]
      description: "File or directory information in E2B sandbox"

    e2b_metrics:
      fields: [cpuPct, memUsedMB, networkIngressMB, networkEgressMB]
      description: "E2B sandbox resource metrics"

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

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

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

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

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

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

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

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

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

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

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

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

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

    # -------------------------------------------------------------------------
    # Postmark email entities
    # -------------------------------------------------------------------------
    postmark_email_result:
      fields: [To, SubmittedAt, MessageID, ErrorCode, Message]
      description: "Result of sending an email via Postmark"

    postmark_bounce:
      fields: [ID, Type, TypeCode, Name, Tag, MessageID, ServerID, Description, Details, Email, From, BouncedAt, DumpAvailable, Inactive, CanActivate, Subject, Content]
      description: "A Postmark bounce record"

    postmark_template:
      fields: [TemplateId, Name, Subject, HtmlBody, TextBody, Alias, TemplateType, LayoutTemplate, Active]
      description: "A Postmark email template"

    postmark_server:
      fields: [ID, Name, Color, SmtpApiActivated, RawEmailEnabled, TrackOpens, TrackLinks, InboundDomain]
      description: "A Postmark server configuration"

    postmark_message_stream:
      fields: [ID, ServerID, Name, Description, MessageStreamType, CreatedAt, UpdatedAt, ArchivedAt]
      description: "A Postmark message stream"

    postmark_outbound_message:
      fields: [Tag, MessageID, To, Cc, Bcc, Recipients, ReceivedAt, From, Subject, Attachments, Status, MessageEvents]
      description: "An outbound message in Postmark"

    postmark_domain:
      fields: [ID, Name, SPFVerified, DKIMVerified, ReturnPathDomainVerified, ReturnPathDomain]
      description: "A Postmark sending domain"

    postmark_sender_signature:
      fields: [ID, Domain, EmailAddress, Name, ReplyToEmailAddress, Confirmed]
      description: "A Postmark sender signature"

    postmark_webhook:
      fields: [ID, Url, MessageStream, HttpAuth, HttpHeaders, Triggers]
      description: "A Postmark webhook configuration"

    postmark_suppression:
      fields: [EmailAddress, SuppressionReason, Origin, CreatedAt]
      description: "A suppressed email address in Postmark"

    postmark_stats:
      fields: [Sent, Bounced, SMTPApiErrors, BounceRate, SpamComplaints, SpamComplaintsRate, Opens, UniqueOpens, Clicks, UniqueClicks, TotalClicks]
      description: "Postmark outbound statistics"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  # ---------------------------------------------------------------------------
  # R) E2B Cloud Sandbox - AI Code Execution Platform (22 tools)
  # ---------------------------------------------------------------------------
  # Environment Variables Required:
  #   E2B_API_KEY - API key from https://e2b.dev/dashboard
  #
  # SDK Packages:
  #   JavaScript/TypeScript: @e2b/code-interpreter, e2b
  #   Python: e2b-code-interpreter, e2b
  #   CLI: @e2b/cli (npm) or e2b (brew)
  # ---------------------------------------------------------------------------

  e2b.createSandbox:
    type: utility
    description: "Creates a new E2B cloud sandbox from a template. Sandboxes are isolated Linux environments for AI code execution with configurable resources and timeout."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: |
          Must use E2B SDK to create sandbox:
          - Import Sandbox from @e2b/code-interpreter or e2b
          - Use Sandbox.create() with template and options
          - Support custom metadata, timeout, and environment variables
      - id: auth_handling
        description: "Must use E2B_API_KEY environment variable for authentication"
      - id: resource_config
        description: "Support configuring CPU cores, memory, and timeout"
    inputs:
      - name: template
        type: string
        optional: true
        description: "Template ID to use (default: base, code-interpreter-v1 for Python/JS)"
      - name: timeoutMs
        type: number
        optional: true
        description: "Sandbox timeout in milliseconds (default: 300000 = 5 minutes)"
      - name: metadata
        type: object
        optional: true
        description: "Custom metadata key-value pairs to attach to sandbox"
      - name: envVars
        type: object
        optional: true
        description: "Environment variables to set in the sandbox"
      - name: cpuCount
        type: number
        optional: true
        description: "Number of CPU cores (1-8)"
      - name: memoryMB
        type: number
        optional: true
        description: "Memory in MB (128-8192)"
    outputs:
      - name: sandboxId
        type: string
        description: "Unique identifier for the sandbox"
      - name: templateId
        type: string
        description: "Template the sandbox was created from"
      - name: clientId
        type: string
        description: "Client ID for WebSocket connections"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.getSandbox:
    type: utility
    description: "Connect to and verify an existing E2B sandbox is running. Returns sandbox ID and connection status."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must use Sandbox.connect() to verify sandbox exists and is accessible"
      - id: error_handling
        description: "Must throw descriptive error when sandbox ID is empty or connection fails"
      - id: input_validation
        description: "Must validate sandboxId is non-empty before connecting"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox to retrieve"
    outputs:
      - name: sandboxId
        type: string
        description: "ID of the connected sandbox"
      - name: templateId
        type: string
        description: "Template ID if available, defaults to 'base'"
      - name: status
        type: string
        description: "Connection status (running)"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.listSandboxes:
    type: utility
    description: "Lists all running E2B sandboxes in your account with their status and metadata."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must use Sandbox.list() to get all running sandboxes"
      - id: filtering
        description: "Support filtering by metadata, template, or status"
    inputs:
      - name: templateId
        type: string
        optional: true
        description: "Filter sandboxes by template ID"
      - name: metadata
        type: object
        optional: true
        description: "Filter sandboxes by metadata key-value pairs"
    outputs:
      - name: sandboxes
        type: e2b_sandbox[]
        description: "Array of running sandboxes"
      - name: count
        type: number
        description: "Total number of sandboxes"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.killSandbox:
    type: utility
    description: "Terminates a running E2B sandbox immediately. All data and processes are destroyed."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must call sandbox.kill() or Sandbox.kill(sandboxId)"
      - id: cleanup
        description: "Ensure proper cleanup and return confirmation"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox to terminate"
    outputs:
      - name: killed
        type: boolean
        description: "Whether the sandbox was successfully terminated"
      - name: sandboxId
        type: string
        description: "ID of the terminated sandbox"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.setTimeout:
    type: utility
    description: "Sets or extends the timeout for an E2B sandbox. The sandbox will be automatically killed when the timeout expires."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must call sandbox.setTimeout() with new timeout value"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox"
      - name: timeoutMs
        type: number
        description: "New timeout in milliseconds from now"
    outputs:
      - name: success
        type: boolean
        description: "Whether the timeout was updated"
      - name: expiresAt
        type: string
        description: "ISO timestamp when sandbox will expire"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.runCode:
    type: utility
    description: "Executes code in an E2B sandbox. Supports Python, JavaScript, TypeScript, R, Java, and Bash with streaming output and result capture."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: |
          Must use sandbox.runCode() for code execution:
          - Support multiple languages via Code Interpreter template
          - Handle stdout, stderr, and results (charts, dataframes)
          - Support streaming output with onStdout/onStderr callbacks
      - id: result_handling
        description: "Must capture and return execution results including display data, errors, and output"
      - id: timeout_handling
        description: "Support configurable execution timeout"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox to execute in"
      - name: code
        type: string
        description: "Code to execute"
      - name: language
        type: string
        optional: true
        description: "Language: python, javascript, typescript, r, java, bash (default: python)"
      - name: timeoutMs
        type: number
        optional: true
        description: "Execution timeout in milliseconds"
      - name: envVars
        type: object
        optional: true
        description: "Environment variables for this execution"
    outputs:
      - name: stdout
        type: string
        description: "Standard output from execution"
      - name: stderr
        type: string
        description: "Standard error from execution"
      - name: results
        type: array
        description: "Execution results (data, charts, dataframes as base64)"
      - name: error
        type: object
        optional: true
        description: "Error details if execution failed"
      - name: duration
        type: number
        description: "Execution duration in milliseconds"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.runCommand:
    type: utility
    description: "Executes a shell command in an E2B sandbox with full shell access. Supports background processes and working directory."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: |
          Must use sandbox.commands.run() for shell commands:
          - Support cwd (working directory) option
          - Support background execution
          - Handle stdin if provided
      - id: process_handling
        description: "Return process ID for background commands"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox"
      - name: command
        type: string
        description: "Shell command to execute"
      - name: cwd
        type: string
        optional: true
        description: "Working directory for the command"
      - name: background
        type: boolean
        optional: true
        description: "Run command in background (default: false)"
      - name: timeoutMs
        type: number
        optional: true
        description: "Command timeout in milliseconds"
    outputs:
      - name: stdout
        type: string
        description: "Standard output"
      - name: stderr
        type: string
        description: "Standard error"
      - name: exitCode
        type: number
        description: "Exit code (0 for success)"
      - name: processId
        type: string
        optional: true
        description: "Process ID if running in background"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.writeFile:
    type: utility
    description: "Writes content to a file in the E2B sandbox filesystem. Creates directories as needed."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must use sandbox.files.write() to write file content"
      - id: encoding_handling
        description: "Support both text (string) and binary (base64) content"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox"
      - name: path
        type: string
        description: "Absolute path in sandbox (e.g., /home/user/file.txt)"
      - name: content
        type: string
        description: "File content (string for text, base64 for binary)"
      - name: encoding
        type: string
        optional: true
        description: "Content encoding: utf-8 (default) or base64"
    outputs:
      - name: success
        type: boolean
        description: "Whether the file was written"
      - name: path
        type: string
        description: "Path of the written file"
      - name: size
        type: number
        description: "Size of the written file in bytes"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.readFile:
    type: utility
    description: "Reads content from a file in the E2B sandbox filesystem."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must use sandbox.files.read() to read file content"
      - id: encoding_handling
        description: "Support returning content as text or base64 for binary files"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox"
      - name: path
        type: string
        description: "Absolute path to file in sandbox"
      - name: encoding
        type: string
        optional: true
        description: "Return encoding: utf-8 (default) or base64"
    outputs:
      - name: content
        type: string
        description: "File content (string or base64)"
      - name: path
        type: string
        description: "Path of the read file"
      - name: size
        type: number
        description: "File size in bytes"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.listFiles:
    type: utility
    description: "Lists files and directories at a path in the E2B sandbox."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must use sandbox.files.list() to list directory contents"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox"
      - name: path
        type: string
        description: "Absolute path to list (e.g., /home/user)"
    outputs:
      - name: entries
        type: e2b_file_info[]
        description: "Array of files and directories"
      - name: count
        type: number
        description: "Total number of entries"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.uploadFile:
    type: utility
    description: "Uploads a file to the E2B sandbox from base64 content or a URL."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must use sandbox.files.write() with proper content handling"
      - id: url_handling
        description: "Support fetching from URL and uploading to sandbox"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox"
      - name: path
        type: string
        description: "Destination path in sandbox"
      - name: content
        type: string
        optional: true
        description: "Base64 encoded file content"
      - name: url
        type: string
        optional: true
        description: "URL to fetch file from (alternative to content)"
    outputs:
      - name: success
        type: boolean
        description: "Whether the upload succeeded"
      - name: path
        type: string
        description: "Path where file was uploaded"
      - name: size
        type: number
        description: "Size of uploaded file in bytes"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.downloadFile:
    type: utility
    description: "Downloads a file from the E2B sandbox as base64 content."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must use sandbox.files.read() and return base64 encoded content"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox"
      - name: path
        type: string
        description: "Path to file in sandbox"
    outputs:
      - name: content
        type: string
        description: "Base64 encoded file content"
      - name: filename
        type: string
        description: "Name of the downloaded file"
      - name: size
        type: number
        description: "File size in bytes"
      - name: mimeType
        type: string
        description: "Detected MIME type of the file"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.makeDirectory:
    type: utility
    description: "Creates a directory in the E2B sandbox filesystem. Creates parent directories as needed."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must use sandbox.files.makeDir() to create directory"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox"
      - name: path
        type: string
        description: "Absolute path of directory to create"
    outputs:
      - name: success
        type: boolean
        description: "Whether the directory was created"
      - name: path
        type: string
        description: "Path of the created directory"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.watchDirectory:
    type: utility
    description: "Watches a directory in the E2B sandbox for file changes. Returns the initial state and supports registering for change events."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must use sandbox.files.watch() for filesystem watching"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox"
      - name: path
        type: string
        description: "Directory path to watch"
    outputs:
      - name: entries
        type: e2b_file_info[]
        description: "Current contents of the directory"
      - name: watcherId
        type: string
        description: "Watcher ID for stopping the watch"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.pauseSandbox:
    type: utility
    description: "Disconnect from an E2B sandbox while keeping it running. The sandbox continues running in the cloud and can be reconnected using resumeSandbox."
    path: "e2b"
    domain_rules:
      - id: cache_management
        description: "Must remove sandbox from local cache to release connection"
      - id: state_preservation
        description: "Sandbox state is preserved in the cloud while disconnected"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox to disconnect from"
    outputs:
      - name: success
        type: boolean
        description: "Whether the disconnect succeeded"
      - name: sandboxId
        type: string
        description: "ID of the disconnected sandbox (use with resumeSandbox to reconnect)"
      - name: status
        type: string
        description: "Connection status (disconnected)"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.resumeSandbox:
    type: utility
    description: "Reconnect to a running E2B sandbox that was previously disconnected using pauseSandbox. Optionally set a new timeout."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must use Sandbox.connect() to reconnect to sandbox"
      - id: error_handling
        description: "Must throw descriptive error if sandbox no longer exists or connection fails"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox to reconnect to"
      - name: timeoutMs
        type: number
        optional: true
        description: "New timeout for the sandbox in milliseconds"
    outputs:
      - name: sandboxId
        type: string
        description: "ID of the reconnected sandbox"
      - name: status
        type: string
        description: "Status of the sandbox after resume"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.setEnvVars:
    type: utility
    description: "Sets environment variables in an E2B sandbox. These are available to all subsequent code executions."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must set environment variables during sandbox creation or via API"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox"
      - name: envVars
        type: object
        description: "Key-value pairs of environment variables to set"
    outputs:
      - name: success
        type: boolean
        description: "Whether the environment variables were set"
      - name: count
        type: number
        description: "Number of environment variables set"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.getMetrics:
    type: utility
    description: "Retrieves resource usage metrics for an E2B sandbox including CPU, memory, and network usage."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must use sandbox.getMetrics() to retrieve usage statistics"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox"
    outputs:
      - name: cpuPct
        type: number
        description: "CPU usage percentage"
      - name: memUsedMB
        type: number
        description: "Memory used in MB"
      - name: networkIngressMB
        type: number
        description: "Network ingress in MB"
      - name: networkEgressMB
        type: number
        description: "Network egress in MB"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  e2b.installPackages:
    type: utility
    description: "Installs Python packages in an E2B Code Interpreter sandbox using pip."
    path: "e2b"
    domain_rules:
      - id: sdk_integration
        description: "Must use sandbox.runCode() with pip install or sandbox.notebook.installPackages()"
    inputs:
      - name: sandboxId
        type: string
        description: "ID of the sandbox"
      - name: packages
        type: array
        description: "Array of package names to install (e.g., ['numpy', 'pandas==2.0.0'])"
    outputs:
      - name: success
        type: boolean
        description: "Whether all packages were installed"
      - name: installed
        type: array
        description: "List of successfully installed packages"
      - name: errors
        type: array
        optional: true
        description: "List of packages that failed to install"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ===========================================================================
  # POSTMARK — Email API tools (82 tools)
  # ===========================================================================

  # --- Email Sending ---

  ops.sendEmail:
    type: utility
    description: "Send a single transactional email via Postmark."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /email endpoint"
    inputs:
      - name: From
        type: string
        description: "Sender email address"
      - name: To
        type: string
        description: "Recipient email address(es)"
      - name: Subject
        type: string
        optional: true
        description: "Email subject line"
      - name: HtmlBody
        type: string
        optional: true
        description: "HTML body"
      - name: TextBody
        type: string
        optional: true
        description: "Plain text body"
    outputs:
      - name: To
        type: string
        description: "Recipient address"
      - name: MessageID
        type: string
        description: "Postmark message ID"
      - name: SubmittedAt
        type: string
        description: "Submission timestamp"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.sendBatchEmails:
    type: utility
    description: "Send a batch of up to 500 emails in a single API call."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /email/batch endpoint"
    inputs:
      - name: Messages
        type: array
        description: "Array of email messages (max 500)"
    outputs:
      - name: results
        type: postmark_email_result[]
        description: "Array of send results"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.sendEmailWithTemplate:
    type: utility
    description: "Send an email using a Postmark template."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /email/withTemplate endpoint"
    inputs:
      - name: TemplateId
        type: number
        optional: true
        description: "Numeric template ID"
      - name: TemplateAlias
        type: string
        optional: true
        description: "Template alias string"
      - name: TemplateModel
        type: object
        description: "Template variable values"
      - name: From
        type: string
        description: "Sender email address"
      - name: To
        type: string
        description: "Recipient email address"
    outputs:
      - name: MessageID
        type: string
        description: "Postmark message ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.sendBatchWithTemplates:
    type: utility
    description: "Send a batch of templated emails in a single API call (max 500)."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /email/batchWithTemplates endpoint"
    inputs:
      - name: Messages
        type: array
        description: "Array of templated email messages"
    outputs:
      - name: results
        type: postmark_email_result[]
        description: "Array of send results"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Bulk Email ---

  ops.sendBulkEmail:
    type: utility
    description: "Submit a bulk email job for large-scale sending."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /email/bulk endpoint"
    inputs:
      - name: From
        type: string
        description: "Sender email address"
      - name: To
        type: string
        description: "Recipient email address(es)"
    outputs:
      - name: JobId
        type: string
        description: "Bulk job ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getBulkEmailStatus:
    type: utility
    description: "Get the status of a bulk email job."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /email/bulk/{id} endpoint"
    inputs:
      - name: id
        type: string
        description: "Bulk email job ID"
    outputs:
      - name: status
        type: object
        description: "Bulk job status"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Bounces ---

  ops.getDeliveryStats:
    type: utility
    description: "Get delivery statistics including bounce counts by type."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /deliverystats endpoint"
    inputs: []
    outputs:
      - name: InactiveMails
        type: number
        description: "Count of inactive emails"
      - name: Bounces
        type: array
        description: "Bounce counts by type"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.searchBounces:
    type: utility
    description: "Search bounces with optional filters like type, date range, and email."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /bounces endpoint"
    inputs:
      - name: count
        type: number
        description: "Number of bounces to return"
      - name: offset
        type: number
        description: "Number of bounces to skip"
      - name: type
        type: string
        optional: true
        description: "Bounce type filter"
    outputs:
      - name: TotalCount
        type: number
        description: "Total matching bounces"
      - name: Bounces
        type: postmark_bounce[]
        description: "Array of bounce records"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getBounce:
    type: utility
    description: "Get details of a specific bounce by ID."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /bounces/{id} endpoint"
    inputs:
      - name: id
        type: number
        description: "Bounce ID"
    outputs:
      - name: bounce
        type: postmark_bounce
        description: "Bounce details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getBounceDump:
    type: utility
    description: "Get the raw SMTP dump for a specific bounce."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /bounces/{id}/dump endpoint"
    inputs:
      - name: id
        type: number
        description: "Bounce ID"
    outputs:
      - name: Body
        type: string
        description: "Raw SMTP dump content"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.activateBounce:
    type: utility
    description: "Activate a bounced email address to allow sending again."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PUT /bounces/{id}/activate endpoint"
    inputs:
      - name: id
        type: number
        description: "Bounce ID to activate"
    outputs:
      - name: Message
        type: string
        description: "Activation result message"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Templates ---

  ops.listTemplates:
    type: utility
    description: "List email templates with optional filtering by type."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /templates endpoint"
    inputs:
      - name: Count
        type: number
        description: "Number of templates to return"
      - name: Offset
        type: number
        description: "Number of templates to skip"
    outputs:
      - name: TotalCount
        type: number
        description: "Total templates"
      - name: Templates
        type: postmark_template[]
        description: "Array of templates"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getTemplate:
    type: utility
    description: "Get details of a specific template by ID or alias."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /templates/{id} endpoint"
    inputs:
      - name: templateIdOrAlias
        type: string
        description: "Template ID or alias"
    outputs:
      - name: template
        type: postmark_template
        description: "Template details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.createTemplate:
    type: utility
    description: "Create a new email template."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /templates endpoint"
    inputs:
      - name: Name
        type: string
        description: "Template name"
      - name: Subject
        type: string
        optional: true
        description: "Default subject line"
      - name: HtmlBody
        type: string
        optional: true
        description: "HTML body"
      - name: TextBody
        type: string
        optional: true
        description: "Text body"
    outputs:
      - name: TemplateId
        type: number
        description: "New template ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.updateTemplate:
    type: utility
    description: "Update an existing email template."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PUT /templates/{id} endpoint"
    inputs:
      - name: templateIdOrAlias
        type: string
        description: "Template ID or alias"
      - name: Name
        type: string
        optional: true
        description: "Template name"
    outputs:
      - name: TemplateId
        type: number
        description: "Updated template ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.deleteTemplate:
    type: utility
    description: "Delete an email template."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API DELETE /templates/{id} endpoint"
    inputs:
      - name: templateIdOrAlias
        type: string
        description: "Template ID or alias to delete"
    outputs:
      - name: ErrorCode
        type: number
        description: "Error code (0 = success)"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.validateTemplate:
    type: utility
    description: "Validate template content and test render with a model."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /templates/validate endpoint"
    inputs:
      - name: Subject
        type: string
        optional: true
        description: "Subject line to validate"
      - name: HtmlBody
        type: string
        optional: true
        description: "HTML body to validate"
    outputs:
      - name: AllContentIsValid
        type: boolean
        description: "Whether all content is valid"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.pushTemplates:
    type: utility
    description: "Push templates from one server to another. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PUT /templates/push endpoint with account token"
    inputs:
      - name: SourceServerID
        type: number
        description: "Source server ID"
      - name: DestinationServerID
        type: number
        description: "Destination server ID"
      - name: PerformChanges
        type: boolean
        description: "Apply changes or dry-run"
    outputs:
      - name: TotalCount
        type: number
        description: "Total templates compared"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Server Config ---

  ops.getServer:
    type: utility
    description: "Get the current server configuration."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /server endpoint"
    inputs: []
    outputs:
      - name: server
        type: postmark_server
        description: "Server configuration"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.updateServer:
    type: utility
    description: "Update the current server configuration."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PUT /server endpoint"
    inputs:
      - name: Name
        type: string
        optional: true
        description: "Server name"
      - name: TrackOpens
        type: boolean
        optional: true
        description: "Enable open tracking"
    outputs:
      - name: server
        type: postmark_server
        description: "Updated server configuration"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Servers Management ---

  ops.listServers:
    type: utility
    description: "List all servers in the account. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /servers endpoint with account token"
    inputs:
      - name: count
        type: number
        description: "Number of servers to return"
      - name: offset
        type: number
        description: "Number of servers to skip"
    outputs:
      - name: TotalCount
        type: number
        description: "Total servers"
      - name: Servers
        type: postmark_server[]
        description: "Array of servers"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getServerById:
    type: utility
    description: "Get a specific server by ID. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /servers/{id} endpoint with account token"
    inputs:
      - name: id
        type: number
        description: "Server ID"
    outputs:
      - name: server
        type: postmark_server
        description: "Server details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.createServer:
    type: utility
    description: "Create a new server in the account. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /servers endpoint with account token"
    inputs:
      - name: Name
        type: string
        description: "Server name"
    outputs:
      - name: server
        type: postmark_server
        description: "Created server"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.updateServerById:
    type: utility
    description: "Update a specific server by ID. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PUT /servers/{id} endpoint with account token"
    inputs:
      - name: id
        type: number
        description: "Server ID"
      - name: Name
        type: string
        optional: true
        description: "Server name"
    outputs:
      - name: server
        type: postmark_server
        description: "Updated server"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.deleteServer:
    type: utility
    description: "Delete a server from the account. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API DELETE /servers/{id} endpoint with account token"
    inputs:
      - name: id
        type: number
        description: "Server ID to delete"
    outputs:
      - name: result
        type: object
        description: "Deletion result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Message Streams ---

  ops.listMessageStreams:
    type: utility
    description: "List all message streams for the server."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /message-streams endpoint"
    inputs:
      - name: MessageStreamType
        type: string
        optional: true
        description: "Filter by stream type"
    outputs:
      - name: MessageStreams
        type: postmark_message_stream[]
        description: "Array of message streams"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getMessageStream:
    type: utility
    description: "Get details of a specific message stream."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /message-streams/{id} endpoint"
    inputs:
      - name: id
        type: string
        description: "Message stream ID"
    outputs:
      - name: stream
        type: postmark_message_stream
        description: "Message stream details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.createMessageStream:
    type: utility
    description: "Create a new message stream."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /message-streams endpoint"
    inputs:
      - name: ID
        type: string
        description: "Unique stream ID"
      - name: Name
        type: string
        description: "Display name"
      - name: MessageStreamType
        type: string
        description: "Stream type (Transactional or Broadcasts)"
    outputs:
      - name: stream
        type: postmark_message_stream
        description: "Created message stream"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.updateMessageStream:
    type: utility
    description: "Update a message stream's name or description."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PATCH /message-streams/{id} endpoint"
    inputs:
      - name: id
        type: string
        description: "Message stream ID"
      - name: Name
        type: string
        optional: true
        description: "New display name"
    outputs:
      - name: stream
        type: postmark_message_stream
        description: "Updated message stream"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.archiveMessageStream:
    type: utility
    description: "Archive a message stream."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /message-streams/{id}/archive endpoint"
    inputs:
      - name: id
        type: string
        description: "Message stream ID to archive"
    outputs:
      - name: result
        type: object
        description: "Archive result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.unarchiveMessageStream:
    type: utility
    description: "Unarchive a previously archived message stream."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /message-streams/{id}/unarchive endpoint"
    inputs:
      - name: id
        type: string
        description: "Message stream ID to unarchive"
    outputs:
      - name: result
        type: object
        description: "Unarchive result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Messages — Outbound ---

  ops.searchOutboundMessages:
    type: utility
    description: "Search outbound messages with optional filters."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /messages/outbound endpoint"
    inputs:
      - name: count
        type: number
        description: "Number of messages to return"
      - name: offset
        type: number
        description: "Number of messages to skip"
    outputs:
      - name: TotalCount
        type: number
        description: "Total matching messages"
      - name: Messages
        type: postmark_outbound_message[]
        description: "Array of messages"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getOutboundMessageDetails:
    type: utility
    description: "Get full details of a specific outbound message."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /messages/outbound/{id}/details endpoint"
    inputs:
      - name: id
        type: string
        description: "Message ID"
    outputs:
      - name: message
        type: postmark_outbound_message
        description: "Message details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getOutboundMessageDump:
    type: utility
    description: "Get the raw SMTP dump of an outbound message."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /messages/outbound/{id}/dump endpoint"
    inputs:
      - name: id
        type: string
        description: "Message ID"
    outputs:
      - name: Body
        type: string
        description: "Raw SMTP dump"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getOutboundMessageOpens:
    type: utility
    description: "Get open events for a specific outbound message."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /messages/outbound/opens/{id} endpoint"
    inputs:
      - name: id
        type: string
        description: "Message ID"
    outputs:
      - name: Opens
        type: array
        description: "Array of open events"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getOutboundMessageClicks:
    type: utility
    description: "Get click events for a specific outbound message."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /messages/outbound/clicks/{id} endpoint"
    inputs:
      - name: id
        type: string
        description: "Message ID"
    outputs:
      - name: Clicks
        type: array
        description: "Array of click events"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Messages — Inbound ---

  ops.searchInboundMessages:
    type: utility
    description: "Search inbound messages with optional filters."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /messages/inbound endpoint"
    inputs:
      - name: count
        type: number
        description: "Number of messages to return"
      - name: offset
        type: number
        description: "Number of messages to skip"
    outputs:
      - name: TotalCount
        type: number
        description: "Total matching messages"
      - name: InboundMessages
        type: array
        description: "Array of inbound messages"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getInboundMessageDetails:
    type: utility
    description: "Get full details of a specific inbound message."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /messages/inbound/{id}/details endpoint"
    inputs:
      - name: id
        type: string
        description: "Inbound message ID"
    outputs:
      - name: message
        type: object
        description: "Inbound message details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.bypassInboundRules:
    type: utility
    description: "Bypass inbound rules for a specific message, reprocessing it."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PUT /messages/inbound/{id}/bypass endpoint"
    inputs:
      - name: id
        type: string
        description: "Inbound message ID"
    outputs:
      - name: result
        type: object
        description: "Bypass result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.retryInboundMessage:
    type: utility
    description: "Retry processing of an inbound message."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PUT /messages/inbound/{id}/retry endpoint"
    inputs:
      - name: id
        type: string
        description: "Inbound message ID"
    outputs:
      - name: result
        type: object
        description: "Retry result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Messages — Search Opens/Clicks ---

  ops.searchMessageOpens:
    type: utility
    description: "Search message open events across all outbound messages."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /messages/outbound/opens endpoint"
    inputs:
      - name: count
        type: number
        description: "Number of results"
      - name: offset
        type: number
        description: "Number to skip"
    outputs:
      - name: Opens
        type: array
        description: "Array of open events"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.searchMessageClicks:
    type: utility
    description: "Search message click events across all outbound messages."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /messages/outbound/clicks endpoint"
    inputs:
      - name: count
        type: number
        description: "Number of results"
      - name: offset
        type: number
        description: "Number to skip"
    outputs:
      - name: Clicks
        type: array
        description: "Array of click events"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Stats ---

  ops.getStatsOverview:
    type: utility
    description: "Get an overview of outbound email statistics."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /stats/outbound endpoint"
    inputs:
      - name: tag
        type: string
        optional: true
        description: "Filter by tag"
      - name: fromdate
        type: string
        optional: true
        description: "Start date"
      - name: todate
        type: string
        optional: true
        description: "End date"
    outputs:
      - name: stats
        type: postmark_stats
        description: "Statistics overview"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getStatsSends:
    type: utility
    description: "Get send count statistics over time."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /stats/outbound/sends endpoint"
    inputs:
      - name: tag
        type: string
        optional: true
      - name: fromdate
        type: string
        optional: true
      - name: todate
        type: string
        optional: true
    outputs:
      - name: Days
        type: array
        description: "Daily send counts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getStatsBounces:
    type: utility
    description: "Get bounce statistics over time."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /stats/outbound/bounces endpoint"
    inputs:
      - name: tag
        type: string
        optional: true
      - name: fromdate
        type: string
        optional: true
      - name: todate
        type: string
        optional: true
    outputs:
      - name: Days
        type: array
        description: "Daily bounce counts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getStatsSpamComplaints:
    type: utility
    description: "Get spam complaint statistics over time."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /stats/outbound/spam endpoint"
    inputs:
      - name: tag
        type: string
        optional: true
      - name: fromdate
        type: string
        optional: true
      - name: todate
        type: string
        optional: true
    outputs:
      - name: Days
        type: array
        description: "Daily spam complaint counts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getStatsTracked:
    type: utility
    description: "Get tracked email statistics over time."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /stats/outbound/tracked endpoint"
    inputs:
      - name: tag
        type: string
        optional: true
      - name: fromdate
        type: string
        optional: true
      - name: todate
        type: string
        optional: true
    outputs:
      - name: Days
        type: array
        description: "Daily tracked counts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getStatsOpens:
    type: utility
    description: "Get email open statistics over time."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /stats/outbound/opens endpoint"
    inputs:
      - name: tag
        type: string
        optional: true
      - name: fromdate
        type: string
        optional: true
      - name: todate
        type: string
        optional: true
    outputs:
      - name: Days
        type: array
        description: "Daily open counts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getStatsOpensByPlatform:
    type: utility
    description: "Get email open statistics grouped by platform."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /stats/outbound/opens/platforms endpoint"
    inputs:
      - name: tag
        type: string
        optional: true
      - name: fromdate
        type: string
        optional: true
      - name: todate
        type: string
        optional: true
    outputs:
      - name: Days
        type: array
        description: "Platform-grouped open counts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getStatsOpensByClient:
    type: utility
    description: "Get email open statistics grouped by email client."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /stats/outbound/opens/emailclients endpoint"
    inputs:
      - name: tag
        type: string
        optional: true
      - name: fromdate
        type: string
        optional: true
      - name: todate
        type: string
        optional: true
    outputs:
      - name: Days
        type: array
        description: "Client-grouped open counts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getStatsClicks:
    type: utility
    description: "Get link click statistics over time."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /stats/outbound/clicks endpoint"
    inputs:
      - name: tag
        type: string
        optional: true
      - name: fromdate
        type: string
        optional: true
      - name: todate
        type: string
        optional: true
    outputs:
      - name: Days
        type: array
        description: "Daily click counts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getStatsClicksByBrowser:
    type: utility
    description: "Get link click statistics grouped by browser family."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /stats/outbound/clicks/browserfamilies endpoint"
    inputs:
      - name: tag
        type: string
        optional: true
      - name: fromdate
        type: string
        optional: true
      - name: todate
        type: string
        optional: true
    outputs:
      - name: Days
        type: array
        description: "Browser-grouped click counts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getStatsClicksByPlatform:
    type: utility
    description: "Get link click statistics grouped by platform."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /stats/outbound/clicks/platforms endpoint"
    inputs:
      - name: tag
        type: string
        optional: true
      - name: fromdate
        type: string
        optional: true
      - name: todate
        type: string
        optional: true
    outputs:
      - name: Days
        type: array
        description: "Platform-grouped click counts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getStatsClicksByLocation:
    type: utility
    description: "Get link click statistics grouped by geographic location."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /stats/outbound/clicks/location endpoint"
    inputs:
      - name: tag
        type: string
        optional: true
      - name: fromdate
        type: string
        optional: true
      - name: todate
        type: string
        optional: true
    outputs:
      - name: Days
        type: array
        description: "Location-grouped click counts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Domains ---

  ops.listDomains:
    type: utility
    description: "List all domains in the account. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /domains endpoint with account token"
    inputs:
      - name: count
        type: number
        description: "Number of domains to return"
      - name: offset
        type: number
        description: "Number of domains to skip"
    outputs:
      - name: TotalCount
        type: number
        description: "Total domains"
      - name: Domains
        type: postmark_domain[]
        description: "Array of domains"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getDomain:
    type: utility
    description: "Get details of a specific domain. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /domains/{id} endpoint with account token"
    inputs:
      - name: id
        type: number
        description: "Domain ID"
    outputs:
      - name: domain
        type: postmark_domain
        description: "Domain details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.createDomain:
    type: utility
    description: "Create a new sending domain. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /domains endpoint with account token"
    inputs:
      - name: Name
        type: string
        description: "Domain name"
    outputs:
      - name: domain
        type: postmark_domain
        description: "Created domain"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.updateDomain:
    type: utility
    description: "Update a domain's return-path. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PUT /domains/{id} endpoint with account token"
    inputs:
      - name: id
        type: number
        description: "Domain ID"
      - name: ReturnPathDomain
        type: string
        optional: true
        description: "New return-path domain"
    outputs:
      - name: domain
        type: postmark_domain
        description: "Updated domain"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.deleteDomain:
    type: utility
    description: "Delete a domain from the account. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API DELETE /domains/{id} endpoint with account token"
    inputs:
      - name: id
        type: number
        description: "Domain ID to delete"
    outputs:
      - name: result
        type: object
        description: "Deletion result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.verifyDomainDkim:
    type: utility
    description: "Trigger DKIM verification for a domain. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PUT /domains/{id}/verifyDkim endpoint"
    inputs:
      - name: id
        type: number
        description: "Domain ID"
    outputs:
      - name: domain
        type: postmark_domain
        description: "Domain with updated DKIM status"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.verifyDomainReturnPath:
    type: utility
    description: "Trigger return-path verification for a domain. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PUT /domains/{id}/verifyReturnPath endpoint"
    inputs:
      - name: id
        type: number
        description: "Domain ID"
    outputs:
      - name: domain
        type: postmark_domain
        description: "Domain with updated return-path status"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.verifyDomainSpf:
    type: utility
    description: "Trigger SPF verification for a domain. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /domains/{id}/verifyspf endpoint"
    inputs:
      - name: id
        type: number
        description: "Domain ID"
    outputs:
      - name: domain
        type: postmark_domain
        description: "Domain with updated SPF status"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.rotateDomainDkim:
    type: utility
    description: "Rotate DKIM keys for a domain. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /domains/{id}/rotatedkim endpoint"
    inputs:
      - name: id
        type: number
        description: "Domain ID"
    outputs:
      - name: result
        type: object
        description: "DKIM rotation result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Sender Signatures ---

  ops.listSenderSignatures:
    type: utility
    description: "List all sender signatures in the account. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /senders endpoint with account token"
    inputs:
      - name: count
        type: number
        description: "Number of signatures to return"
      - name: offset
        type: number
        description: "Number of signatures to skip"
    outputs:
      - name: TotalCount
        type: number
        description: "Total signatures"
      - name: SenderSignatures
        type: postmark_sender_signature[]
        description: "Array of sender signatures"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getSenderSignature:
    type: utility
    description: "Get details of a specific sender signature. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /senders/{id} endpoint with account token"
    inputs:
      - name: id
        type: number
        description: "Sender signature ID"
    outputs:
      - name: signature
        type: postmark_sender_signature
        description: "Sender signature details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.createSenderSignature:
    type: utility
    description: "Create a new sender signature. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /senders endpoint with account token"
    inputs:
      - name: FromEmail
        type: string
        description: "Sender email address"
      - name: Name
        type: string
        description: "Sender display name"
    outputs:
      - name: signature
        type: postmark_sender_signature
        description: "Created sender signature"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.updateSenderSignature:
    type: utility
    description: "Update an existing sender signature. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PUT /senders/{id} endpoint with account token"
    inputs:
      - name: id
        type: number
        description: "Sender signature ID"
      - name: Name
        type: string
        optional: true
        description: "Sender display name"
    outputs:
      - name: signature
        type: postmark_sender_signature
        description: "Updated sender signature"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.deleteSenderSignature:
    type: utility
    description: "Delete a sender signature. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API DELETE /senders/{id} endpoint with account token"
    inputs:
      - name: id
        type: number
        description: "Sender signature ID to delete"
    outputs:
      - name: result
        type: object
        description: "Deletion result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendSenderConfirmation:
    type: utility
    description: "Resend the confirmation email for a sender signature. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /senders/{id}/resend endpoint with account token"
    inputs:
      - name: id
        type: number
        description: "Sender signature ID"
    outputs:
      - name: result
        type: object
        description: "Resend result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Webhooks ---

  ops.listWebhooks:
    type: utility
    description: "List all webhooks for the server."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /webhooks endpoint"
    inputs:
      - name: MessageStream
        type: string
        optional: true
        description: "Filter by message stream"
    outputs:
      - name: Webhooks
        type: postmark_webhook[]
        description: "Array of webhooks"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getWebhook:
    type: utility
    description: "Get details of a specific webhook."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /webhooks/{id} endpoint"
    inputs:
      - name: id
        type: number
        description: "Webhook ID"
    outputs:
      - name: webhook
        type: postmark_webhook
        description: "Webhook details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.createWebhook:
    type: utility
    description: "Create a new webhook."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /webhooks endpoint"
    inputs:
      - name: Url
        type: string
        description: "Webhook endpoint URL"
      - name: Triggers
        type: object
        optional: true
        description: "Event triggers to enable"
    outputs:
      - name: webhook
        type: postmark_webhook
        description: "Created webhook"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.updateWebhook:
    type: utility
    description: "Update an existing webhook."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API PUT /webhooks/{id} endpoint"
    inputs:
      - name: id
        type: number
        description: "Webhook ID"
      - name: Url
        type: string
        optional: true
        description: "Webhook endpoint URL"
    outputs:
      - name: webhook
        type: postmark_webhook
        description: "Updated webhook"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.deleteWebhook:
    type: utility
    description: "Delete a webhook."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API DELETE /webhooks/{id} endpoint"
    inputs:
      - name: id
        type: number
        description: "Webhook ID to delete"
    outputs:
      - name: result
        type: object
        description: "Deletion result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Suppressions ---

  ops.listSuppressions:
    type: utility
    description: "List suppressed email addresses for a message stream."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /message-streams/{streamId}/suppressions/dump endpoint"
    inputs:
      - name: streamId
        type: string
        description: "Message stream ID"
    outputs:
      - name: Suppressions
        type: postmark_suppression[]
        description: "Array of suppressed addresses"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.createSuppressions:
    type: utility
    description: "Add email addresses to the suppression list for a message stream."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /message-streams/{streamId}/suppressions endpoint"
    inputs:
      - name: streamId
        type: string
        description: "Message stream ID"
      - name: Suppressions
        type: array
        description: "Email addresses to suppress"
    outputs:
      - name: Suppressions
        type: array
        description: "Results of suppression operations"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.deleteSuppressions:
    type: utility
    description: "Remove email addresses from the suppression list."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /message-streams/{streamId}/suppressions/delete endpoint"
    inputs:
      - name: streamId
        type: string
        description: "Message stream ID"
      - name: Suppressions
        type: array
        description: "Email addresses to unsuppress"
    outputs:
      - name: Suppressions
        type: array
        description: "Results of unsuppression operations"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Inbound Rules ---

  ops.listInboundRules:
    type: utility
    description: "List all inbound processing rules."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /triggers/inboundrules endpoint"
    inputs:
      - name: count
        type: number
        description: "Number of rules to return"
      - name: offset
        type: number
        description: "Number of rules to skip"
    outputs:
      - name: TotalCount
        type: number
        description: "Total rules"
      - name: InboundRules
        type: array
        description: "Array of inbound rules"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.createInboundRule:
    type: utility
    description: "Create a new inbound processing rule to block emails matching a pattern."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /triggers/inboundrules endpoint"
    inputs:
      - name: Rule
        type: string
        description: "Email address or domain pattern to block"
    outputs:
      - name: ID
        type: number
        description: "Created rule ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.deleteInboundRule:
    type: utility
    description: "Delete an inbound processing rule."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API DELETE /triggers/inboundrules/{id} endpoint"
    inputs:
      - name: id
        type: number
        description: "Inbound rule ID to delete"
    outputs:
      - name: result
        type: object
        description: "Deletion result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # --- Data Removals ---

  ops.createDataRemoval:
    type: utility
    description: "Request removal of personal data associated with an email address. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API POST /data-removals endpoint with account token"
    inputs:
      - name: RequestedBy
        type: string
        description: "Email of the person requesting removal"
      - name: RequestedFor
        type: string
        description: "Email address whose data should be removed"
    outputs:
      - name: ID
        type: number
        description: "Data removal request ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.getDataRemovalStatus:
    type: utility
    description: "Get the status of a data removal request. Uses account token."
    path: "postmark"
    domain_rules:
      - id: api_integration
        description: "Must call Postmark API GET /data-removals/{id} endpoint with account token"
    inputs:
      - name: id
        type: number
        description: "Data removal request ID"
    outputs:
      - name: Status
        type: string
        description: "Current status of the removal request"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ─── Resend Email API ──────────────────────────────────────────────────────

  ops.resendSendEmail:
    type: utility
    description: "Send a single email via the Resend API."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API POST /emails endpoint"
    inputs:
      - name: from
        type: string
        description: "Sender email address"
      - name: to
        type: string | string[]
        description: "Recipient email address(es)"
      - name: subject
        type: string
        description: "Email subject line"
      - name: html
        type: string
        optional: true
        description: "HTML body content"
      - name: text
        type: string
        optional: true
        description: "Plain text body content"
    outputs:
      - name: id
        type: string
        description: "Resend email ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendSendBatchEmails:
    type: utility
    description: "Send a batch of emails in a single API call via Resend."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API POST /emails/batch endpoint"
    inputs:
      - name: emails
        type: array
        description: "Array of email objects to send"
    outputs:
      - name: data
        type: array
        description: "Array of created email IDs"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendGetEmail:
    type: utility
    description: "Retrieve details of a sent email by its ID."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API GET /emails/{id} endpoint"
    inputs:
      - name: id
        type: string
        description: "The email ID to retrieve"
    outputs:
      - name: result
        type: object
        description: "Email details including status and content"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendUpdateEmail:
    type: utility
    description: "Update a scheduled email's delivery time."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API PATCH /emails/{id} endpoint"
    inputs:
      - name: id
        type: string
        description: "The email ID to update"
      - name: scheduled_at
        type: string
        description: "New scheduled time in ISO 8601 format"
    outputs:
      - name: id
        type: string
        description: "Updated email ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendCancelEmail:
    type: utility
    description: "Cancel a scheduled email that has not been sent yet."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API POST /emails/{id}/cancel endpoint"
    inputs:
      - name: id
        type: string
        description: "The email ID to cancel"
    outputs:
      - name: id
        type: string
        description: "Cancelled email ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendListEmails:
    type: utility
    description: "List sent emails with cursor-based pagination."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API GET /emails endpoint"
    inputs:
      - name: limit
        type: number
        optional: true
        description: "Max results to return"
      - name: after
        type: string
        optional: true
        description: "Cursor for forward pagination"
      - name: before
        type: string
        optional: true
        description: "Cursor for backward pagination"
    outputs:
      - name: data
        type: array
        description: "Array of email summaries"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendCreateDomain:
    type: utility
    description: "Add a new sending domain to your Resend account."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API POST /domains endpoint"
    inputs:
      - name: name
        type: string
        description: "Domain name to add"
      - name: region
        type: string
        optional: true
        description: "Region for the domain"
    outputs:
      - name: result
        type: object
        description: "Domain details with DNS records"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendGetDomain:
    type: utility
    description: "Retrieve details and DNS records for a specific domain."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API GET /domains/{id} endpoint"
    inputs:
      - name: domain_id
        type: string
        description: "The domain ID to retrieve"
    outputs:
      - name: result
        type: object
        description: "Domain details including verification status"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendUpdateDomain:
    type: utility
    description: "Update tracking and TLS settings for an existing domain."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API PATCH /domains/{id} endpoint"
    inputs:
      - name: domain_id
        type: string
        description: "The domain ID to update"
      - name: click_tracking
        type: boolean
        optional: true
        description: "Enable or disable click tracking"
    outputs:
      - name: id
        type: string
        description: "Updated domain ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendDeleteDomain:
    type: utility
    description: "Delete a sending domain from your Resend account."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API DELETE /domains/{id} endpoint"
    inputs:
      - name: domain_id
        type: string
        description: "The domain ID to delete"
    outputs:
      - name: deleted
        type: boolean
        description: "Whether deletion succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendListDomains:
    type: utility
    description: "List all sending domains with their verification status."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API GET /domains endpoint"
    inputs:
      - name: limit
        type: number
        optional: true
        description: "Max results to return"
    outputs:
      - name: data
        type: array
        description: "Array of domain objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendVerifyDomain:
    type: utility
    description: "Trigger DNS verification for a sending domain."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API POST /domains/{id}/verify endpoint"
    inputs:
      - name: domain_id
        type: string
        description: "The domain ID to verify"
    outputs:
      - name: id
        type: string
        description: "Verified domain ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendCreateApiKey:
    type: utility
    description: "Create a new Resend API key."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API POST /api-keys endpoint"
    inputs:
      - name: name
        type: string
        description: "Name for the API key"
      - name: permission
        type: string
        optional: true
        description: "Permission level"
    outputs:
      - name: id
        type: string
        description: "Created API key ID"
      - name: token
        type: string
        description: "The API key token"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendListApiKeys:
    type: utility
    description: "List all API keys in your Resend account."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API GET /api-keys endpoint"
    inputs:
      - name: limit
        type: number
        optional: true
        description: "Max results to return"
    outputs:
      - name: data
        type: array
        description: "Array of API key objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendDeleteApiKey:
    type: utility
    description: "Delete an API key from your Resend account."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API DELETE /api-keys/{id} endpoint"
    inputs:
      - name: api_key_id
        type: string
        description: "The API key ID to delete"
    outputs:
      - name: result
        type: object
        description: "Deletion confirmation"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendCreateContact:
    type: utility
    description: "Create a new contact with email and optional properties."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API POST /contacts endpoint"
    inputs:
      - name: email
        type: string
        description: "Contact email address"
      - name: first_name
        type: string
        optional: true
        description: "Contact first name"
      - name: last_name
        type: string
        optional: true
        description: "Contact last name"
    outputs:
      - name: id
        type: string
        description: "Created contact ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendGetContact:
    type: utility
    description: "Retrieve a contact by ID or email address."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API GET /contacts/{id} endpoint"
    inputs:
      - name: id
        type: string
        description: "Contact ID or email address"
    outputs:
      - name: result
        type: object
        description: "Contact details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendUpdateContact:
    type: utility
    description: "Update a contact's name, subscription status, or properties."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API PATCH /contacts/{id} endpoint"
    inputs:
      - name: id
        type: string
        description: "Contact ID or email address"
      - name: first_name
        type: string
        optional: true
        description: "Updated first name"
    outputs:
      - name: id
        type: string
        description: "Updated contact ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendDeleteContact:
    type: utility
    description: "Delete a contact by ID or email address."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API DELETE /contacts/{id} endpoint"
    inputs:
      - name: id
        type: string
        description: "Contact ID or email to delete"
    outputs:
      - name: deleted
        type: boolean
        description: "Whether deletion succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendListContacts:
    type: utility
    description: "List contacts with optional segment filtering and pagination."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API GET /contacts endpoint"
    inputs:
      - name: segment_id
        type: string
        optional: true
        description: "Filter by segment ID"
      - name: limit
        type: number
        optional: true
        description: "Max results to return"
    outputs:
      - name: data
        type: array
        description: "Array of contact objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendCreateBroadcast:
    type: utility
    description: "Create a broadcast email draft to send to a segment."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API POST /broadcasts endpoint"
    inputs:
      - name: segment_id
        type: string
        description: "Segment ID to target"
      - name: from
        type: string
        description: "Sender address"
      - name: subject
        type: string
        description: "Broadcast subject line"
    outputs:
      - name: id
        type: string
        description: "Created broadcast ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendListBroadcasts:
    type: utility
    description: "List all broadcasts with status and scheduling details."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API GET /broadcasts endpoint"
    inputs:
      - name: limit
        type: number
        optional: true
        description: "Max results to return"
    outputs:
      - name: data
        type: array
        description: "Array of broadcast objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendSendBroadcast:
    type: utility
    description: "Send or schedule a previously created broadcast."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API POST /broadcasts/{id}/send endpoint"
    inputs:
      - name: broadcast_id
        type: string
        description: "The broadcast ID to send"
      - name: scheduled_at
        type: string
        optional: true
        description: "ISO 8601 datetime to schedule"
    outputs:
      - name: id
        type: string
        description: "Sent broadcast ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendDeleteBroadcast:
    type: utility
    description: "Delete a draft broadcast that has not been sent."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API DELETE /broadcasts/{id} endpoint"
    inputs:
      - name: broadcast_id
        type: string
        description: "The broadcast ID to delete"
    outputs:
      - name: deleted
        type: boolean
        description: "Whether deletion succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendCreateAudience:
    type: utility
    description: "Create a new audience for organizing contacts."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API POST /audiences endpoint"
    inputs:
      - name: name
        type: string
        description: "Audience name"
    outputs:
      - name: id
        type: string
        description: "Created audience ID"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendListAudiences:
    type: utility
    description: "List all audiences in your Resend account."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API GET /audiences endpoint"
    inputs:
      - name: limit
        type: number
        optional: true
        description: "Max results to return"
    outputs:
      - name: data
        type: array
        description: "Array of audience objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendGetAudience:
    type: utility
    description: "Retrieve details of a specific audience."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API GET /audiences/{id} endpoint"
    inputs:
      - name: audience_id
        type: string
        description: "The audience ID to retrieve"
    outputs:
      - name: result
        type: object
        description: "Audience details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.resendDeleteAudience:
    type: utility
    description: "Delete an audience from your Resend account."
    path: "resend"
    domain_rules:
      - id: api_integration
        description: "Must call Resend API DELETE /audiences/{id} endpoint"
    inputs:
      - name: audience_id
        type: string
        description: "The audience ID to delete"
    outputs:
      - name: deleted
        type: boolean
        description: "Whether deletion succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ─── Moltbook Social Network ──────────────────────────────────────

  communication.moltbookRegister:
    type: utility
    description: "Register a new AI agent on Moltbook and get an API key and claim URL."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API POST /agents/register endpoint"
    inputs:
      - name: name
        type: string
        description: "Agent name for Moltbook profile"
      - name: description
        type: string
        description: "Short description of the agent"
    outputs:
      - name: agent
        type: object
        description: "Agent registration details with api_key and claim_url"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookCheckStatus:
    type: utility
    description: "Check the claim status of your Moltbook agent account."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API GET /agents/status endpoint"
    inputs: []
    outputs:
      - name: status
        type: string
        description: "Claim status: pending_claim or claimed"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookGetProfile:
    type: utility
    description: "Get a Moltbook agent profile — your own or another agent's."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API GET /agents/me or /agents/profile endpoint"
    inputs:
      - name: name
        type: string
        optional: true
        description: "Agent name to look up. Omit for own profile."
    outputs:
      - name: agent
        type: object
        description: "Agent profile with karma, followers, recent posts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookUpdateProfile:
    type: utility
    description: "Update your Moltbook agent profile description or metadata."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API PATCH /agents/me endpoint"
    inputs:
      - name: description
        type: string
        optional: true
        description: "New profile description"
      - name: metadata
        type: object
        optional: true
        description: "Metadata key-value pairs"
    outputs:
      - name: success
        type: boolean
        description: "Whether the update succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookCreatePost:
    type: utility
    description: "Create a text or link post in a Moltbook submolt community."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API POST /posts endpoint"
    inputs:
      - name: submolt
        type: string
        description: "Submolt community to post in"
      - name: title
        type: string
        description: "Post title"
      - name: content
        type: string
        optional: true
        description: "Post body text"
      - name: url
        type: string
        optional: true
        description: "URL to share for link posts"
    outputs:
      - name: post
        type: object
        description: "Created post data"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookGetPost:
    type: utility
    description: "Get a single Moltbook post by its ID."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API GET /posts/{id} endpoint"
    inputs:
      - name: postId
        type: string
        description: "The post ID to retrieve"
    outputs:
      - name: post
        type: object
        description: "Post data with votes and metadata"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookGetFeed:
    type: utility
    description: "Get posts from Moltbook — personalized feed, global feed, or submolt-specific."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API GET /feed, /posts, or /submolts/{name}/feed endpoint"
    inputs:
      - name: feedType
        type: string
        optional: true
        description: "Feed type: personalized or global"
      - name: submolt
        type: string
        optional: true
        description: "Filter to a specific submolt"
      - name: sort
        type: string
        optional: true
        description: "Sort order: hot, new, top, rising"
      - name: limit
        type: number
        optional: true
        description: "Max posts to return"
    outputs:
      - name: posts
        type: array
        description: "Array of post objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookDeletePost:
    type: utility
    description: "Delete your own Moltbook post."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API DELETE /posts/{id} endpoint"
    inputs:
      - name: postId
        type: string
        description: "The post ID to delete"
    outputs:
      - name: success
        type: boolean
        description: "Whether deletion succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookCreateComment:
    type: utility
    description: "Add a comment on a Moltbook post or reply to an existing comment."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API POST /posts/{id}/comments endpoint"
    inputs:
      - name: postId
        type: string
        description: "The post ID to comment on"
      - name: content
        type: string
        description: "Comment text"
      - name: parentId
        type: string
        optional: true
        description: "Parent comment ID for threaded replies"
    outputs:
      - name: comment
        type: object
        description: "Created comment data"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookGetComments:
    type: utility
    description: "Get comments on a Moltbook post."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API GET /posts/{id}/comments endpoint"
    inputs:
      - name: postId
        type: string
        description: "The post ID to get comments for"
      - name: sort
        type: string
        optional: true
        description: "Sort order: top, new, controversial"
    outputs:
      - name: comments
        type: array
        description: "Array of comment objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookVote:
    type: utility
    description: "Upvote or downvote a Moltbook post or comment."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API POST /posts/{id}/upvote or /comments/{id}/upvote endpoint"
    inputs:
      - name: targetType
        type: string
        description: "Whether voting on a post or comment"
      - name: targetId
        type: string
        description: "The post or comment ID"
      - name: direction
        type: string
        description: "Vote direction: upvote or downvote"
    outputs:
      - name: success
        type: boolean
        description: "Whether the vote succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookCreateSubmolt:
    type: utility
    description: "Create a new submolt community on Moltbook."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API POST /submolts endpoint"
    inputs:
      - name: name
        type: string
        description: "URL-safe submolt name"
      - name: displayName
        type: string
        description: "Display name"
      - name: description
        type: string
        description: "Community description"
    outputs:
      - name: submolt
        type: object
        description: "Created submolt data"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookListSubmolts:
    type: utility
    description: "List all available submolt communities on Moltbook."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API GET /submolts endpoint"
    inputs: []
    outputs:
      - name: submolts
        type: array
        description: "Array of submolt objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookGetSubmolt:
    type: utility
    description: "Get detailed information about a specific Moltbook submolt."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API GET /submolts/{name} endpoint"
    inputs:
      - name: name
        type: string
        description: "Submolt name to look up"
    outputs:
      - name: submolt
        type: object
        description: "Submolt details with member count and role"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookSubscribe:
    type: utility
    description: "Subscribe to or unsubscribe from a Moltbook submolt community."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API POST or DELETE /submolts/{name}/subscribe endpoint"
    inputs:
      - name: name
        type: string
        description: "Submolt name"
      - name: action
        type: string
        description: "subscribe or unsubscribe"
    outputs:
      - name: success
        type: boolean
        description: "Whether the action succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookFollow:
    type: utility
    description: "Follow or unfollow another agent on Moltbook."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API POST or DELETE /agents/{name}/follow endpoint"
    inputs:
      - name: name
        type: string
        description: "Agent name to follow or unfollow"
      - name: action
        type: string
        description: "follow or unfollow"
    outputs:
      - name: success
        type: boolean
        description: "Whether the action succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookSearch:
    type: utility
    description: "Search Moltbook using AI-powered semantic search by meaning."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API GET /search endpoint with query parameter"
    inputs:
      - name: query
        type: string
        description: "Search query — natural language"
      - name: type
        type: string
        optional: true
        description: "What to search: all, posts, comments"
      - name: limit
        type: number
        optional: true
        description: "Max results"
    outputs:
      - name: results
        type: array
        description: "Array of search results with similarity scores"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookDmCheck:
    type: utility
    description: "Check for new DM activity — pending requests and unread messages."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API GET /agents/dm/check endpoint"
    inputs: []
    outputs:
      - name: activity
        type: object
        description: "DM activity summary with requests and unread counts"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookDmRequest:
    type: utility
    description: "Initiate a direct message conversation with another Moltbook agent."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API POST /agents/dm/request endpoint"
    inputs:
      - name: to
        type: string
        description: "Name of the agent to message"
      - name: toOwner
        type: string
        optional: true
        description: "Target agent owner's X handle"
      - name: message
        type: string
        description: "Initial message (10-1000 chars)"
    outputs:
      - name: conversation
        type: object
        description: "Created conversation request data"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookDmGetConversations:
    type: utility
    description: "List DM conversations or get messages from a specific conversation."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API GET /agents/dm/conversations endpoint"
    inputs:
      - name: conversationId
        type: string
        optional: true
        description: "Specific conversation ID, or omit to list all"
    outputs:
      - name: conversations
        type: array | object
        description: "List of conversations or single conversation with messages"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookDmReply:
    type: utility
    description: "Send a reply in an existing Moltbook DM conversation."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API POST /agents/dm/conversations/{id}/send endpoint"
    inputs:
      - name: conversationId
        type: string
        description: "Conversation ID to reply in"
      - name: message
        type: string
        description: "Message to send"
      - name: needsHumanInput
        type: boolean
        optional: true
        description: "Flag for owner escalation"
    outputs:
      - name: success
        type: boolean
        description: "Whether the message was sent"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookDmManageRequest:
    type: utility
    description: "Approve or reject a pending DM request on Moltbook."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API POST /agents/dm/requests/{id}/approve or /reject endpoint"
    inputs:
      - name: conversationId
        type: string
        description: "Conversation ID of the pending request"
      - name: action
        type: string
        description: "approve or reject"
      - name: block
        type: boolean
        optional: true
        description: "Block future requests when rejecting"
    outputs:
      - name: success
        type: boolean
        description: "Whether the action succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookDmGetRequests:
    type: utility
    description: "List all pending DM requests on Moltbook."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API GET /agents/dm/requests endpoint"
    inputs: []
    outputs:
      - name: requests
        type: array
        description: "Array of pending DM requests"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookPinPost:
    type: utility
    description: "Pin or unpin a post in a submolt you moderate."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API POST or DELETE /posts/{id}/pin endpoint"
    inputs:
      - name: postId
        type: string
        description: "Post ID to pin or unpin"
      - name: action
        type: string
        description: "pin or unpin"
    outputs:
      - name: success
        type: boolean
        description: "Whether the action succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  communication.moltbookManageModerator:
    type: utility
    description: "Add or remove a moderator from a submolt you own."
    path: "moltbook"
    domain_rules:
      - id: api_integration
        description: "Must call Moltbook API POST or DELETE /submolts/{name}/moderators endpoint"
    inputs:
      - name: submoltName
        type: string
        description: "Submolt name"
      - name: agentName
        type: string
        description: "Agent name to add or remove"
      - name: action
        type: string
        description: "add or remove"
    outputs:
      - name: success
        type: boolean
        description: "Whether the action succeeded"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ─── GitHub API ──────────────────────────────────────────────────────────

  ops.githubGetRepo:
    type: utility
    description: "Get details of a GitHub repository including stars, forks, and language."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo} endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
    outputs:
      - name: repository
        type: object
        description: "Repository details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubListRepos:
    type: utility
    description: "List repositories for a user or organization with optional filtering."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /users/{username}/repos endpoint"
    inputs:
      - name: username
        type: string
        description: "GitHub username"
      - name: sort
        type: string
        optional: true
        description: "Sort field"
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: repositories
        type: array
        description: "Array of repository objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubCreateIssue:
    type: utility
    description: "Create a new issue on a GitHub repository."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API POST /repos/{owner}/{repo}/issues endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: title
        type: string
        description: "Issue title"
      - name: body
        type: string
        optional: true
        description: "Issue body"
    outputs:
      - name: issue
        type: object
        description: "Created issue"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubGetIssue:
    type: utility
    description: "Get details of a specific issue by number."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo}/issues/{issue_number} endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: issue_number
        type: number
        description: "Issue number"
    outputs:
      - name: issue
        type: object
        description: "Issue details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubListIssues:
    type: utility
    description: "List issues on a repository with state and label filters."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo}/issues endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: state
        type: string
        optional: true
        description: "Filter by state"
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: issues
        type: array
        description: "Array of issue objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubCreateIssueComment:
    type: utility
    description: "Add a comment to an existing GitHub issue or pull request."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API POST /repos/{owner}/{repo}/issues/{issue_number}/comments endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: issue_number
        type: number
        description: "Issue number"
      - name: body
        type: string
        description: "Comment body"
    outputs:
      - name: comment
        type: object
        description: "Created comment"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubGetPullRequest:
    type: utility
    description: "Get details of a specific pull request by number."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo}/pulls/{pull_number} endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: pull_number
        type: number
        description: "Pull request number"
    outputs:
      - name: pullRequest
        type: object
        description: "Pull request details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubListPullRequests:
    type: utility
    description: "List pull requests on a repository with state and head/base filters."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo}/pulls endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: state
        type: string
        optional: true
        description: "Filter by state"
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: pullRequests
        type: array
        description: "Array of pull request objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubGetFileContent:
    type: utility
    description: "Get the contents of a file or directory from a GitHub repository."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo}/contents/{path} endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: path
        type: string
        description: "File path"
      - name: ref
        type: string
        optional: true
        description: "Branch or commit ref"
    outputs:
      - name: content
        type: object
        description: "File content or directory listing"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubSearchCode:
    type: utility
    description: "Search for code across GitHub repositories."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /search/code endpoint"
    inputs:
      - name: q
        type: string
        description: "Search query"
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: results
        type: object
        description: "Search results with items"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubSearchRepositories:
    type: utility
    description: "Search GitHub repositories by query with sort and order options."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /search/repositories endpoint"
    inputs:
      - name: q
        type: string
        description: "Search query"
      - name: sort
        type: string
        optional: true
        description: "Sort field"
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: results
        type: object
        description: "Search results with items"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubListBranches:
    type: utility
    description: "List branches on a GitHub repository."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo}/branches endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: branches
        type: array
        description: "Array of branch objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubGetCommit:
    type: utility
    description: "Get details of a specific commit by SHA."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo}/commits/{ref} endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: ref
        type: string
        description: "Commit SHA or ref"
    outputs:
      - name: commit
        type: object
        description: "Commit details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubListCommits:
    type: utility
    description: "List commits on a repository with optional path and author filters."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo}/commits endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: path
        type: string
        optional: true
        description: "File path filter"
      - name: author
        type: string
        optional: true
        description: "Author filter"
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: commits
        type: array
        description: "Array of commit objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubListReleases:
    type: utility
    description: "List releases on a GitHub repository."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo}/releases endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: releases
        type: array
        description: "Array of release objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubGetRelease:
    type: utility
    description: "Get details of a specific release by tag name."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo}/releases/tags/{tag} endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: tag
        type: string
        description: "Release tag name"
    outputs:
      - name: release
        type: object
        description: "Release details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubCreateGist:
    type: utility
    description: "Create a new GitHub Gist with one or more files."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API POST /gists endpoint"
    inputs:
      - name: files
        type: object
        description: "Files to include in gist"
      - name: description
        type: string
        optional: true
        description: "Gist description"
      - name: public
        type: boolean
        optional: true
        description: "Whether gist is public"
    outputs:
      - name: gist
        type: object
        description: "Created gist"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubListGists:
    type: utility
    description: "List gists for the authenticated user or a specific user."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /gists or GET /users/{username}/gists endpoint"
    inputs:
      - name: username
        type: string
        optional: true
        description: "GitHub username"
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: gists
        type: array
        description: "Array of gist objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubListWorkflowRuns:
    type: utility
    description: "List recent GitHub Actions workflow runs for a repository."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo}/actions/runs endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: status
        type: string
        optional: true
        description: "Filter by status"
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: workflowRuns
        type: object
        description: "Workflow runs with total count"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.githubGetWorkflowRun:
    type: utility
    description: "Get details of a specific GitHub Actions workflow run."
    path: "github"
    domain_rules:
      - id: api_integration
        description: "Must call GitHub API GET /repos/{owner}/{repo}/actions/runs/{run_id} endpoint"
    inputs:
      - name: owner
        type: string
        description: "Repository owner"
      - name: repo
        type: string
        description: "Repository name"
      - name: run_id
        type: number
        description: "Workflow run ID"
    outputs:
      - name: workflowRun
        type: object
        description: "Workflow run details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ─── Vercel API ─────────────────────────────────────────────────────────

  ops.vercelListDeployments:
    type: utility
    description: "List deployments for a project or team with optional state filtering."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API GET /v6/deployments endpoint"
    inputs:
      - name: projectId
        type: string
        optional: true
        description: "Project ID to filter"
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
      - name: limit
        type: number
        optional: true
        description: "Max results"
    outputs:
      - name: deployments
        type: array
        description: "Array of deployment objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelGetDeployment:
    type: utility
    description: "Get details of a specific deployment by ID or URL."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API GET /v13/deployments/{idOrUrl} endpoint"
    inputs:
      - name: idOrUrl
        type: string
        description: "Deployment ID or URL"
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
    outputs:
      - name: deployment
        type: object
        description: "Deployment details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelCancelDeployment:
    type: utility
    description: "Cancel a deployment that is currently building."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API PATCH /v12/deployments/{id}/cancel endpoint"
    inputs:
      - name: id
        type: string
        description: "Deployment ID"
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
    outputs:
      - name: result
        type: object
        description: "Cancellation result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelListProjects:
    type: utility
    description: "List all projects in your Vercel account or team."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API GET /v9/projects endpoint"
    inputs:
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
      - name: limit
        type: number
        optional: true
        description: "Max results"
      - name: search
        type: string
        optional: true
        description: "Search query"
    outputs:
      - name: projects
        type: array
        description: "Array of project objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelGetProject:
    type: utility
    description: "Get details of a specific Vercel project by name or ID."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API GET /v9/projects/{idOrName} endpoint"
    inputs:
      - name: idOrName
        type: string
        description: "Project ID or name"
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
    outputs:
      - name: project
        type: object
        description: "Project details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelListDomains:
    type: utility
    description: "List all domains configured in your Vercel account."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API GET /v5/domains endpoint"
    inputs:
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
      - name: limit
        type: number
        optional: true
        description: "Max results"
    outputs:
      - name: domains
        type: array
        description: "Array of domain objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelGetDomain:
    type: utility
    description: "Get details and configuration for a specific domain."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API GET /v5/domains/{name} endpoint"
    inputs:
      - name: name
        type: string
        description: "Domain name"
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
    outputs:
      - name: domain
        type: object
        description: "Domain details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelListProjectDomains:
    type: utility
    description: "List all domains assigned to a specific project."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API GET /v9/projects/{idOrName}/domains endpoint"
    inputs:
      - name: idOrName
        type: string
        description: "Project ID or name"
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
    outputs:
      - name: domains
        type: array
        description: "Array of project domain objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelListEnvVars:
    type: utility
    description: "List environment variables for a Vercel project."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API GET /v9/projects/{idOrName}/env endpoint"
    inputs:
      - name: idOrName
        type: string
        description: "Project ID or name"
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
    outputs:
      - name: envVars
        type: array
        description: "Array of environment variable objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelCreateEnvVar:
    type: utility
    description: "Create a new environment variable on a Vercel project."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API POST /v10/projects/{idOrName}/env endpoint"
    inputs:
      - name: idOrName
        type: string
        description: "Project ID or name"
      - name: key
        type: string
        description: "Variable name"
      - name: value
        type: string
        description: "Variable value"
      - name: target
        type: array
        description: "Target environments"
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
    outputs:
      - name: envVar
        type: object
        description: "Created environment variable"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelDeleteEnvVar:
    type: utility
    description: "Delete an environment variable from a Vercel project."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API DELETE /v9/projects/{idOrName}/env/{envId} endpoint"
    inputs:
      - name: idOrName
        type: string
        description: "Project ID or name"
      - name: envId
        type: string
        description: "Environment variable ID"
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
    outputs:
      - name: result
        type: object
        description: "Deletion result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelGetDeploymentEvents:
    type: utility
    description: "Get build logs and runtime events for a deployment."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API GET /v3/deployments/{idOrUrl}/events endpoint"
    inputs:
      - name: idOrUrl
        type: string
        description: "Deployment ID or URL"
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
    outputs:
      - name: events
        type: array
        description: "Array of deployment events"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelGetUsage:
    type: utility
    description: "Get billing usage and consumption data (requests, bandwidth, invocations) for a date range."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API GET /v1/billing/charges endpoint with JSONL response parsing"
    inputs:
      - name: from
        type: string
        description: "Start date in ISO 8601 UTC format (inclusive)"
      - name: to
        type: string
        description: "End date in ISO 8601 UTC format (exclusive)"
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
    outputs:
      - name: summary
        type: array
        description: "Usage aggregated by service name with total cost and quantity"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.vercelGetRuntimeLogs:
    type: utility
    description: "Get runtime request logs for a deployment (method, path, status code, source)."
    path: "vercel"
    domain_rules:
      - id: api_integration
        description: "Must call Vercel API GET /v1/projects/{projectId}/deployments/{deploymentId}/runtime-logs endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Project ID"
      - name: deploymentId
        type: string
        description: "Deployment ID"
      - name: teamId
        type: string
        optional: true
        description: "Team ID for scoping"
    outputs:
      - name: logs
        type: array
        description: "Array of runtime log entries"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ─── Neon Serverless Postgres ──────────────────────────────────────────

  ops.neonListProjects:
    type: utility
    description: "List all Neon projects with optional search filtering."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API GET /projects endpoint"
    inputs:
      - name: search
        type: string
        optional: true
        description: "Search by project name or ID"
      - name: limit
        type: number
        optional: true
        description: "Max results (default 10, max 400)"
    outputs:
      - name: projects
        type: array
        description: "Array of project objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonGetProject:
    type: utility
    description: "Get details of a specific Neon project by ID."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API GET /projects/{project_id} endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID"
    outputs:
      - name: project
        type: object
        description: "Project details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonCreateProject:
    type: utility
    description: "Create a new Neon project with a default branch and database."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API POST /projects endpoint"
    inputs:
      - name: name
        type: string
        optional: true
        description: "Project name"
      - name: regionId
        type: string
        optional: true
        description: "Deployment region"
      - name: pgVersion
        type: number
        optional: true
        description: "PostgreSQL major version"
    outputs:
      - name: project
        type: object
        description: "Created project with connection URIs"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonDeleteProject:
    type: utility
    description: "Permanently delete a Neon project and all its resources."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API DELETE /projects/{project_id} endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID to delete"
    outputs:
      - name: project
        type: object
        description: "Deleted project details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonListBranches:
    type: utility
    description: "List all branches in a Neon project."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API GET /projects/{project_id}/branches endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID"
    outputs:
      - name: branches
        type: array
        description: "Array of branch objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonCreateBranch:
    type: utility
    description: "Create a new branch from a parent branch in a Neon project."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API POST /projects/{project_id}/branches endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID"
      - name: name
        type: string
        optional: true
        description: "Branch name"
      - name: parentBranchId
        type: string
        optional: true
        description: "Parent branch ID to fork from"
    outputs:
      - name: branch
        type: object
        description: "Created branch with endpoints"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonDeleteBranch:
    type: utility
    description: "Delete a branch from a Neon project."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API DELETE /projects/{project_id}/branches/{branch_id} endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID"
      - name: branchId
        type: string
        description: "Branch ID to delete"
    outputs:
      - name: branch
        type: object
        description: "Deleted branch details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonListDatabases:
    type: utility
    description: "List all databases on a specific branch."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API GET /projects/{project_id}/branches/{branch_id}/databases endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID"
      - name: branchId
        type: string
        description: "Branch ID"
    outputs:
      - name: databases
        type: array
        description: "Array of database objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonCreateDatabase:
    type: utility
    description: "Create a new database on a branch."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API POST /projects/{project_id}/branches/{branch_id}/databases endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID"
      - name: branchId
        type: string
        description: "Branch ID"
      - name: name
        type: string
        description: "Database name"
      - name: ownerName
        type: string
        description: "Owner role name"
    outputs:
      - name: database
        type: object
        description: "Created database details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonDeleteDatabase:
    type: utility
    description: "Delete a database from a branch."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API DELETE /projects/{project_id}/branches/{branch_id}/databases/{database_name} endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID"
      - name: branchId
        type: string
        description: "Branch ID"
      - name: databaseName
        type: string
        description: "Database name to delete"
    outputs:
      - name: database
        type: object
        description: "Deleted database details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonListEndpoints:
    type: utility
    description: "List compute endpoints for a Neon project."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API GET /projects/{project_id}/endpoints endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID"
    outputs:
      - name: endpoints
        type: array
        description: "Array of endpoint objects with status and config"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonStartEndpoint:
    type: utility
    description: "Start a suspended compute endpoint."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API POST /projects/{project_id}/endpoints/{endpoint_id}/start endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID"
      - name: endpointId
        type: string
        description: "Endpoint ID to start"
    outputs:
      - name: endpoint
        type: object
        description: "Started endpoint details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonSuspendEndpoint:
    type: utility
    description: "Suspend a running compute endpoint to save costs."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API POST /projects/{project_id}/endpoints/{endpoint_id}/suspend endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID"
      - name: endpointId
        type: string
        description: "Endpoint ID to suspend"
    outputs:
      - name: endpoint
        type: object
        description: "Suspended endpoint details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonGetConnectionUri:
    type: utility
    description: "Get a PostgreSQL connection string for a database."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API GET /projects/{project_id}/connection_uri endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID"
      - name: databaseName
        type: string
        description: "Database name"
      - name: roleName
        type: string
        description: "Role name"
      - name: branchId
        type: string
        optional: true
        description: "Branch ID (defaults to default branch)"
    outputs:
      - name: uri
        type: string
        description: "PostgreSQL connection URI"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonListOperations:
    type: utility
    description: "List recent operations for a Neon project."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API GET /projects/{project_id}/operations endpoint"
    inputs:
      - name: projectId
        type: string
        description: "Neon project ID"
      - name: limit
        type: number
        optional: true
        description: "Max results"
    outputs:
      - name: operations
        type: array
        description: "Array of operation objects with status and duration"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.neonGetConsumption:
    type: utility
    description: "Get usage metrics (compute time, storage, data written) for a date range."
    path: "neon"
    domain_rules:
      - id: api_integration
        description: "Must call Neon API GET /consumption_history/account or /consumption_history/projects endpoint"
    inputs:
      - name: from
        type: string
        description: "Start date in ISO 8601 format"
      - name: to
        type: string
        description: "End date in ISO 8601 format"
      - name: granularity
        type: string
        description: "Time granularity: hourly, daily, or monthly"
      - name: projectIds
        type: string
        optional: true
        description: "Comma-separated project IDs to filter"
    outputs:
      - name: consumption
        type: object
        description: "Usage metrics by time period"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ─── Cloudflare API ─────────────────────────────────────────────────────

  ops.cloudflareListZones:
    type: utility
    description: "List Cloudflare zones with optional name and status filtering."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API GET /zones endpoint"
    inputs:
      - name: name
        type: string
        optional: true
        description: "Zone name filter"
      - name: status
        type: string
        optional: true
        description: "Zone status filter"
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: zones
        type: array
        description: "Array of zone objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflareGetZone:
    type: utility
    description: "Get details of a specific Cloudflare zone by ID."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API GET /zones/{zone_id} endpoint"
    inputs:
      - name: zone_id
        type: string
        description: "Zone ID"
    outputs:
      - name: zone
        type: object
        description: "Zone details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflarePurgeCache:
    type: utility
    description: "Purge cached content from a Cloudflare zone by URLs or purge everything."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API POST /zones/{zone_id}/purge_cache endpoint"
    inputs:
      - name: zone_id
        type: string
        description: "Zone ID"
      - name: purge_everything
        type: boolean
        optional: true
        description: "Purge all cached content"
      - name: files
        type: array
        optional: true
        description: "Specific URLs to purge"
    outputs:
      - name: result
        type: object
        description: "Purge result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflareListDnsRecords:
    type: utility
    description: "List DNS records for a Cloudflare zone with type and name filters."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API GET /zones/{zone_id}/dns_records endpoint"
    inputs:
      - name: zone_id
        type: string
        description: "Zone ID"
      - name: type
        type: string
        optional: true
        description: "Record type filter"
      - name: name
        type: string
        optional: true
        description: "Record name filter"
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: records
        type: array
        description: "Array of DNS record objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflareCreateDnsRecord:
    type: utility
    description: "Create a new DNS record in a Cloudflare zone."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API POST /zones/{zone_id}/dns_records endpoint"
    inputs:
      - name: zone_id
        type: string
        description: "Zone ID"
      - name: type
        type: string
        description: "Record type (A, AAAA, CNAME, etc.)"
      - name: name
        type: string
        description: "Record name"
      - name: content
        type: string
        description: "Record content"
      - name: proxied
        type: boolean
        optional: true
        description: "Whether proxied through Cloudflare"
    outputs:
      - name: record
        type: object
        description: "Created DNS record"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflareUpdateDnsRecord:
    type: utility
    description: "Update an existing DNS record in a Cloudflare zone."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API PUT /zones/{zone_id}/dns_records/{record_id} endpoint"
    inputs:
      - name: zone_id
        type: string
        description: "Zone ID"
      - name: record_id
        type: string
        description: "DNS record ID"
      - name: type
        type: string
        description: "Record type"
      - name: name
        type: string
        description: "Record name"
      - name: content
        type: string
        description: "Record content"
      - name: proxied
        type: boolean
        optional: true
        description: "Whether proxied through Cloudflare"
    outputs:
      - name: record
        type: object
        description: "Updated DNS record"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflareDeleteDnsRecord:
    type: utility
    description: "Delete a DNS record from a Cloudflare zone."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API DELETE /zones/{zone_id}/dns_records/{record_id} endpoint"
    inputs:
      - name: zone_id
        type: string
        description: "Zone ID"
      - name: record_id
        type: string
        description: "DNS record ID"
    outputs:
      - name: result
        type: object
        description: "Deletion result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflareListWorkers:
    type: utility
    description: "List all Workers scripts in your Cloudflare account."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API GET /accounts/{account_id}/workers/scripts endpoint"
    inputs: []
    outputs:
      - name: workers
        type: array
        description: "Array of Worker script objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflareGetWorker:
    type: utility
    description: "Get metadata and bindings for a specific Worker script."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API GET /accounts/{account_id}/workers/scripts/{script_name}/settings endpoint"
    inputs:
      - name: script_name
        type: string
        description: "Worker script name"
    outputs:
      - name: worker
        type: object
        description: "Worker metadata and bindings"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflareDeleteWorker:
    type: utility
    description: "Delete a Worker script from your Cloudflare account."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API DELETE /accounts/{account_id}/workers/scripts/{script_name} endpoint"
    inputs:
      - name: script_name
        type: string
        description: "Worker script name"
    outputs:
      - name: result
        type: object
        description: "Deletion result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflareListKvNamespaces:
    type: utility
    description: "List KV namespaces in your Cloudflare account."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API GET /accounts/{account_id}/storage/kv/namespaces endpoint"
    inputs:
      - name: per_page
        type: number
        optional: true
        description: "Results per page"
    outputs:
      - name: namespaces
        type: array
        description: "Array of KV namespace objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflareListKvKeys:
    type: utility
    description: "List keys in a Cloudflare KV namespace with optional prefix filter."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API GET /accounts/{account_id}/storage/kv/namespaces/{namespace_id}/keys endpoint"
    inputs:
      - name: namespace_id
        type: string
        description: "KV namespace ID"
      - name: prefix
        type: string
        optional: true
        description: "Key prefix filter"
      - name: limit
        type: number
        optional: true
        description: "Max results"
    outputs:
      - name: keys
        type: array
        description: "Array of key objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflareGetKvValue:
    type: utility
    description: "Get the value of a key from a Cloudflare KV namespace."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API GET /accounts/{account_id}/storage/kv/namespaces/{namespace_id}/values/{key_name} endpoint"
    inputs:
      - name: namespace_id
        type: string
        description: "KV namespace ID"
      - name: key_name
        type: string
        description: "Key name"
    outputs:
      - name: value
        type: string
        description: "The stored value"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflarePutKvValue:
    type: utility
    description: "Write a key-value pair to a Cloudflare KV namespace."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API PUT /accounts/{account_id}/storage/kv/namespaces/{namespace_id}/values/{key_name} endpoint"
    inputs:
      - name: namespace_id
        type: string
        description: "KV namespace ID"
      - name: key_name
        type: string
        description: "Key name"
      - name: value
        type: string
        description: "Value to store"
    outputs:
      - name: result
        type: object
        description: "Write confirmation"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.cloudflareDeleteKvKey:
    type: utility
    description: "Delete a key from a Cloudflare KV namespace."
    path: "cloudflare"
    domain_rules:
      - id: api_integration
        description: "Must call Cloudflare API DELETE /accounts/{account_id}/storage/kv/namespaces/{namespace_id}/values/{key_name} endpoint"
    inputs:
      - name: namespace_id
        type: string
        description: "KV namespace ID"
      - name: key_name
        type: string
        description: "Key name"
    outputs:
      - name: result
        type: object
        description: "Deletion result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ─── Slack Tools ─────────────────────────────────────────────────────────────

  ops.slackSendMessage:
    type: utility
    description: "Send a message to a Slack channel or thread."
    path: "slack"
    domain_rules:
      - id: api_integration
        description: "Must call Slack API chat.postMessage endpoint"
    inputs:
      - name: channel
        type: string
        description: "Channel ID or name"
      - name: text
        type: string
        description: "Message text"
      - name: thread_ts
        type: string
        optional: true
        description: "Thread timestamp to reply in"
      - name: unfurl_links
        type: boolean
        optional: true
        description: "Enable link unfurling"
    outputs:
      - name: message
        type: object
        description: "Sent message details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.slackListChannels:
    type: utility
    description: "List public and private channels in a Slack workspace."
    path: "slack"
    domain_rules:
      - id: api_integration
        description: "Must call Slack API conversations.list endpoint"
    inputs:
      - name: types
        type: string
        optional: true
        description: "Channel types filter"
      - name: limit
        type: number
        optional: true
        description: "Results per page"
      - name: cursor
        type: string
        optional: true
        description: "Pagination cursor"
    outputs:
      - name: channels
        type: array
        description: "Array of channel objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.slackGetChannel:
    type: utility
    description: "Get detailed information about a specific Slack channel."
    path: "slack"
    domain_rules:
      - id: api_integration
        description: "Must call Slack API conversations.info endpoint"
    inputs:
      - name: channel
        type: string
        description: "Channel ID"
    outputs:
      - name: channel
        type: object
        description: "Channel details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.slackListUsers:
    type: utility
    description: "List all users in a Slack workspace."
    path: "slack"
    domain_rules:
      - id: api_integration
        description: "Must call Slack API users.list endpoint"
    inputs:
      - name: limit
        type: number
        optional: true
        description: "Results per page"
      - name: cursor
        type: string
        optional: true
        description: "Pagination cursor"
    outputs:
      - name: members
        type: array
        description: "Array of user objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.slackGetUser:
    type: utility
    description: "Get profile details of a specific Slack user."
    path: "slack"
    domain_rules:
      - id: api_integration
        description: "Must call Slack API users.info endpoint"
    inputs:
      - name: user
        type: string
        description: "User ID"
    outputs:
      - name: user
        type: object
        description: "User profile details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.slackAddReaction:
    type: utility
    description: "Add an emoji reaction to a Slack message."
    path: "slack"
    domain_rules:
      - id: api_integration
        description: "Must call Slack API reactions.add endpoint"
    inputs:
      - name: channel
        type: string
        description: "Channel ID"
      - name: timestamp
        type: string
        description: "Message timestamp"
      - name: name
        type: string
        description: "Emoji name without colons"
    outputs:
      - name: result
        type: object
        description: "Reaction result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.slackUploadFile:
    type: utility
    description: "Upload a text file or snippet to a Slack channel."
    path: "slack"
    domain_rules:
      - id: api_integration
        description: "Must call Slack API files.upload endpoint"
    inputs:
      - name: channel_id
        type: string
        description: "Channel ID"
      - name: content
        type: string
        description: "File content"
      - name: filename
        type: string
        description: "Filename"
      - name: title
        type: string
        optional: true
        description: "File title"
      - name: initial_comment
        type: string
        optional: true
        description: "Comment with the file"
    outputs:
      - name: file
        type: object
        description: "Uploaded file details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.slackSetChannelTopic:
    type: utility
    description: "Set the topic of a Slack channel."
    path: "slack"
    domain_rules:
      - id: api_integration
        description: "Must call Slack API conversations.setTopic endpoint"
    inputs:
      - name: channel
        type: string
        description: "Channel ID"
      - name: topic
        type: string
        description: "New topic text"
    outputs:
      - name: channel
        type: object
        description: "Updated channel"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.slackListMessages:
    type: utility
    description: "Retrieve recent messages from a Slack channel."
    path: "slack"
    domain_rules:
      - id: api_integration
        description: "Must call Slack API conversations.history endpoint"
    inputs:
      - name: channel
        type: string
        description: "Channel ID"
      - name: limit
        type: number
        optional: true
        description: "Number of messages"
      - name: cursor
        type: string
        optional: true
        description: "Pagination cursor"
      - name: oldest
        type: string
        optional: true
        description: "Messages after this Unix timestamp"
      - name: latest
        type: string
        optional: true
        description: "Messages before this Unix timestamp"
    outputs:
      - name: messages
        type: array
        description: "Array of message objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.slackSearchMessages:
    type: utility
    description: "Search for messages across a Slack workspace."
    path: "slack"
    domain_rules:
      - id: api_integration
        description: "Must call Slack API search.messages endpoint"
    inputs:
      - name: query
        type: string
        description: "Search query"
      - name: sort
        type: string
        optional: true
        description: "Sort by score or timestamp"
      - name: count
        type: number
        optional: true
        description: "Number of results"
    outputs:
      - name: messages
        type: object
        description: "Search results"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ─── Discord Tools ──────────────────────────────────────────────────────────

  ops.discordSendMessage:
    type: utility
    description: "Send a message to a Discord channel."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API POST /channels/{channel_id}/messages endpoint"
    inputs:
      - name: channel_id
        type: string
        description: "Channel ID"
      - name: content
        type: string
        description: "Message content"
      - name: tts
        type: boolean
        optional: true
        description: "Text-to-speech"
    outputs:
      - name: message
        type: object
        description: "Sent message details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordListGuilds:
    type: utility
    description: "List guilds (servers) the bot is a member of."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API GET /users/@me/guilds endpoint"
    inputs:
      - name: limit
        type: number
        optional: true
        description: "Number of guilds"
      - name: before
        type: string
        optional: true
        description: "Get guilds before this ID"
      - name: after
        type: string
        optional: true
        description: "Get guilds after this ID"
    outputs:
      - name: guilds
        type: array
        description: "Array of guild objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordGetGuild:
    type: utility
    description: "Get detailed information about a Discord guild."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API GET /guilds/{guild_id} endpoint"
    inputs:
      - name: guild_id
        type: string
        description: "Guild ID"
      - name: with_counts
        type: boolean
        optional: true
        description: "Include member and presence counts"
    outputs:
      - name: guild
        type: object
        description: "Guild details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordListChannels:
    type: utility
    description: "List all channels in a Discord guild."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API GET /guilds/{guild_id}/channels endpoint"
    inputs:
      - name: guild_id
        type: string
        description: "Guild ID"
    outputs:
      - name: channels
        type: array
        description: "Array of channel objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordGetChannel:
    type: utility
    description: "Get detailed information about a specific Discord channel."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API GET /channels/{channel_id} endpoint"
    inputs:
      - name: channel_id
        type: string
        description: "Channel ID"
    outputs:
      - name: channel
        type: object
        description: "Channel details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordListMessages:
    type: utility
    description: "Retrieve recent messages from a Discord channel."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API GET /channels/{channel_id}/messages endpoint"
    inputs:
      - name: channel_id
        type: string
        description: "Channel ID"
      - name: limit
        type: number
        optional: true
        description: "Number of messages (1-100)"
      - name: before
        type: string
        optional: true
        description: "Get messages before this ID"
      - name: after
        type: string
        optional: true
        description: "Get messages after this ID"
      - name: around
        type: string
        optional: true
        description: "Get messages around this ID"
    outputs:
      - name: messages
        type: array
        description: "Array of message objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordCreateChannel:
    type: utility
    description: "Create a new text or voice channel in a Discord guild."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API POST /guilds/{guild_id}/channels endpoint"
    inputs:
      - name: guild_id
        type: string
        description: "Guild ID"
      - name: name
        type: string
        description: "Channel name"
      - name: type
        type: number
        optional: true
        description: "Channel type (0=text, 2=voice, 4=category, 5=announcement)"
      - name: topic
        type: string
        optional: true
        description: "Channel topic"
      - name: parent_id
        type: string
        optional: true
        description: "Parent category ID"
    outputs:
      - name: channel
        type: object
        description: "Created channel details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordEditMessage:
    type: utility
    description: "Edit a previously sent message in a Discord channel."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API PATCH /channels/{channel_id}/messages/{message_id} endpoint"
    inputs:
      - name: channel_id
        type: string
        description: "Channel ID"
      - name: message_id
        type: string
        description: "Message ID"
      - name: content
        type: string
        description: "New message content"
    outputs:
      - name: message
        type: object
        description: "Updated message"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordDeleteMessage:
    type: utility
    description: "Delete a message from a Discord channel."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API DELETE /channels/{channel_id}/messages/{message_id} endpoint"
    inputs:
      - name: channel_id
        type: string
        description: "Channel ID"
      - name: message_id
        type: string
        description: "Message ID"
    outputs:
      - name: result
        type: object
        description: "Deletion confirmation"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordAddReaction:
    type: utility
    description: "Add an emoji reaction to a Discord message."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API PUT /channels/{channel_id}/messages/{message_id}/reactions/{emoji}/@me endpoint"
    inputs:
      - name: channel_id
        type: string
        description: "Channel ID"
      - name: message_id
        type: string
        description: "Message ID"
      - name: emoji
        type: string
        description: "URL-encoded emoji or custom emoji name:id"
    outputs:
      - name: result
        type: object
        description: "Reaction result"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordListMembers:
    type: utility
    description: "List members of a Discord guild with pagination."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API GET /guilds/{guild_id}/members endpoint"
    inputs:
      - name: guild_id
        type: string
        description: "Guild ID"
      - name: limit
        type: number
        optional: true
        description: "Number of members (1-1000)"
      - name: after
        type: string
        optional: true
        description: "Get members after this user ID"
    outputs:
      - name: members
        type: array
        description: "Array of member objects"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordGetMember:
    type: utility
    description: "Get detailed information about a specific guild member."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API GET /guilds/{guild_id}/members/{user_id} endpoint"
    inputs:
      - name: guild_id
        type: string
        description: "Guild ID"
      - name: user_id
        type: string
        description: "User ID"
    outputs:
      - name: member
        type: object
        description: "Member details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordCreateThread:
    type: utility
    description: "Create a new thread from a message in a Discord channel."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API POST /channels/{channel_id}/messages/{message_id}/threads endpoint"
    inputs:
      - name: channel_id
        type: string
        description: "Channel ID"
      - name: message_id
        type: string
        description: "Message ID"
      - name: name
        type: string
        description: "Thread name"
      - name: auto_archive_duration
        type: number
        optional: true
        description: "Auto-archive duration in minutes"
    outputs:
      - name: thread
        type: object
        description: "Created thread details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordListThreads:
    type: utility
    description: "List active threads in a Discord guild."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API GET /guilds/{guild_id}/threads/active endpoint"
    inputs:
      - name: guild_id
        type: string
        description: "Guild ID"
    outputs:
      - name: threads
        type: object
        description: "Active threads and members"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.discordPinMessage:
    type: utility
    description: "Pin a message in a Discord channel."
    path: "discord"
    domain_rules:
      - id: api_integration
        description: "Must call Discord API PUT /channels/{channel_id}/pins/{message_id} endpoint"
    inputs:
      - name: channel_id
        type: string
        description: "Channel ID"
      - name: message_id
        type: string
        description: "Message ID"
    outputs:
      - name: result
        type: object
        description: "Pin confirmation"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ---------------------------------------------------------------------------
  # AgentMail Tools (email for AI agents)
  # ---------------------------------------------------------------------------
  ops.agentmailCreateInbox:
    type: utility
    description: "Create a new email inbox for an AI agent."
    path: "agentmail"
    domain_rules:
      - id: api_integration
        description: "Must call AgentMail API POST /v0/inboxes endpoint"
    inputs:
      - name: username
        type: string
        optional: true
        description: "Username for the email address"
      - name: domain
        type: string
        optional: true
        description: "Domain for the email address"
      - name: display_name
        type: string
        optional: true
        description: "Display name for the inbox"
    outputs:
      - name: inbox
        type: InboxResult
        description: "Created inbox details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.agentmailListInboxes:
    type: utility
    description: "List all email inboxes in the account."
    path: "agentmail"
    domain_rules:
      - id: api_integration
        description: "Must call AgentMail API GET /v0/inboxes endpoint"
    inputs:
      - name: limit
        type: number
        optional: true
        description: "Max inboxes to return (1-100)"
      - name: page_token
        type: string
        optional: true
        description: "Pagination token"
    outputs:
      - name: result
        type: ListInboxesResult
        description: "List of inboxes with pagination"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.agentmailGetInbox:
    type: utility
    description: "Get details of a specific email inbox."
    path: "agentmail"
    domain_rules:
      - id: api_integration
        description: "Must call AgentMail API GET /v0/inboxes/{inbox_id} endpoint"
    inputs:
      - name: inbox_id
        type: string
        description: "Inbox ID"
    outputs:
      - name: inbox
        type: InboxResult
        description: "Inbox details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.agentmailDeleteInbox:
    type: utility
    description: "Delete an email inbox and all its messages."
    path: "agentmail"
    domain_rules:
      - id: api_integration
        description: "Must call AgentMail API DELETE /v0/inboxes/{inbox_id} endpoint"
    inputs:
      - name: inbox_id
        type: string
        description: "Inbox ID"
    outputs:
      - name: result
        type: SuccessResult
        description: "Deletion confirmation"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.agentmailSendMessage:
    type: utility
    description: "Send an email message from an inbox."
    path: "agentmail"
    domain_rules:
      - id: api_integration
        description: "Must call AgentMail API POST /v0/inboxes/{inbox_id}/messages endpoint"
    inputs:
      - name: inbox_id
        type: string
        description: "Inbox ID to send from"
      - name: to
        type: string
        description: "Recipient email address"
      - name: subject
        type: string
        description: "Email subject"
      - name: text
        type: string
        description: "Plain text body"
      - name: html
        type: string
        optional: true
        description: "HTML body"
    outputs:
      - name: message
        type: MessageResult
        description: "Sent message details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.agentmailReplyToMessage:
    type: utility
    description: "Reply to an existing email message in a thread."
    path: "agentmail"
    domain_rules:
      - id: api_integration
        description: "Must call AgentMail API POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply endpoint"
    inputs:
      - name: inbox_id
        type: string
        description: "Inbox ID"
      - name: message_id
        type: string
        description: "Message ID to reply to"
      - name: text
        type: string
        description: "Reply text"
      - name: html
        type: string
        optional: true
        description: "Reply HTML body"
    outputs:
      - name: message
        type: MessageResult
        description: "Reply message details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.agentmailListMessages:
    type: utility
    description: "List email messages in an inbox."
    path: "agentmail"
    domain_rules:
      - id: api_integration
        description: "Must call AgentMail API GET /v0/inboxes/{inbox_id}/messages endpoint"
    inputs:
      - name: inbox_id
        type: string
        description: "Inbox ID"
      - name: limit
        type: number
        optional: true
        description: "Max messages to return (1-100)"
      - name: page_token
        type: string
        optional: true
        description: "Pagination token"
    outputs:
      - name: result
        type: ListMessagesResult
        description: "List of messages with pagination"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.agentmailGetMessage:
    type: utility
    description: "Get the full details of a specific email message."
    path: "agentmail"
    domain_rules:
      - id: api_integration
        description: "Must call AgentMail API GET /v0/inboxes/{inbox_id}/messages/{message_id} endpoint"
    inputs:
      - name: inbox_id
        type: string
        description: "Inbox ID"
      - name: message_id
        type: string
        description: "Message ID"
    outputs:
      - name: message
        type: MessageResult
        description: "Full message details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.agentmailListThreads:
    type: utility
    description: "List email threads in an inbox, optionally filtered by labels."
    path: "agentmail"
    domain_rules:
      - id: api_integration
        description: "Must call AgentMail API GET /v0/inboxes/{inbox_id}/threads endpoint"
    inputs:
      - name: inbox_id
        type: string
        description: "Inbox ID"
      - name: limit
        type: number
        optional: true
        description: "Max threads to return (1-100)"
      - name: labels
        type: array
        optional: true
        description: "Filter by labels"
    outputs:
      - name: result
        type: ListThreadsResult
        description: "List of threads with pagination"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.agentmailGetThread:
    type: utility
    description: "Get a thread with all its messages for viewing a full conversation."
    path: "agentmail"
    domain_rules:
      - id: api_integration
        description: "Must call AgentMail API GET /v0/inboxes/{inbox_id}/threads/{thread_id} endpoint"
    inputs:
      - name: inbox_id
        type: string
        description: "Inbox ID"
      - name: thread_id
        type: string
        description: "Thread ID"
    outputs:
      - name: thread
        type: ThreadDetailResult
        description: "Thread with all messages"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.agentmailCreateDraft:
    type: utility
    description: "Create an email draft for human-in-the-loop approval."
    path: "agentmail"
    domain_rules:
      - id: api_integration
        description: "Must call AgentMail API POST /v0/inboxes/{inbox_id}/drafts endpoint"
    inputs:
      - name: inbox_id
        type: string
        description: "Inbox ID"
      - name: to
        type: string
        description: "Recipient email"
      - name: subject
        type: string
        description: "Email subject"
      - name: text
        type: string
        description: "Plain text body"
      - name: html
        type: string
        optional: true
        description: "HTML body"
    outputs:
      - name: draft
        type: DraftResult
        description: "Created draft details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.agentmailSendDraft:
    type: utility
    description: "Send a previously created draft, converting it to a sent message."
    path: "agentmail"
    domain_rules:
      - id: api_integration
        description: "Must call AgentMail API POST /v0/inboxes/{inbox_id}/drafts/{draft_id}/send endpoint"
    inputs:
      - name: inbox_id
        type: string
        description: "Inbox ID"
      - name: draft_id
        type: string
        description: "Draft ID"
    outputs:
      - name: message
        type: MessageResult
        description: "Sent message details"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  # ---------------------------------------------------------------------------
  # Supabase Tools (database REST API for AI agents)
  # ---------------------------------------------------------------------------
  ops.supabaseQueryRows:
    type: utility
    description: "Query rows from a Supabase table with filtering, ordering, and pagination using PostgREST syntax."
    path: "supabase"
    domain_rules:
      - id: api_integration
        description: "Must call Supabase PostgREST GET /rest/v1/{table} endpoint with filter params"
    inputs:
      - name: table
        type: string
        description: "Table name to query"
      - name: select
        type: string
        optional: true
        description: "Columns to select"
      - name: filter
        type: string
        optional: true
        description: "PostgREST filter string"
      - name: order
        type: string
        optional: true
        description: "Order by column(s)"
      - name: limit
        type: number
        optional: true
        description: "Maximum rows to return"
      - name: offset
        type: number
        optional: true
        description: "Rows to skip for pagination"
    outputs:
      - name: result
        type: QueryResult
        description: "Array of rows with count"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.supabaseGetRowById:
    type: utility
    description: "Get a single row from a Supabase table by its primary key value."
    path: "supabase"
    domain_rules:
      - id: api_integration
        description: "Must call Supabase PostgREST GET /rest/v1/{table} with eq filter and limit=1"
    inputs:
      - name: table
        type: string
        description: "Table name"
      - name: value
        type: string
        description: "Primary key value"
      - name: column
        type: string
        optional: true
        description: "Primary key column name"
      - name: select
        type: string
        optional: true
        description: "Columns to select"
    outputs:
      - name: result
        type: RowResult
        description: "Single row or null"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.supabaseInsertRows:
    type: utility
    description: "Insert one or more rows into a Supabase table and return the inserted data."
    path: "supabase"
    domain_rules:
      - id: api_integration
        description: "Must call Supabase PostgREST POST /rest/v1/{table} with Prefer: return=representation"
    inputs:
      - name: table
        type: string
        description: "Table name"
      - name: rows
        type: array
        description: "Array of row objects to insert"
      - name: on_conflict
        type: string
        optional: true
        description: "Conflict resolution columns"
      - name: returning
        type: string
        optional: true
        description: "Columns to return"
    outputs:
      - name: result
        type: InsertResult
        description: "Inserted rows with count"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.supabaseUpdateRows:
    type: utility
    description: "Update rows in a Supabase table matching a PostgREST filter condition."
    path: "supabase"
    domain_rules:
      - id: api_integration
        description: "Must call Supabase PostgREST PATCH /rest/v1/{table} with filter params and Prefer: return=representation"
    inputs:
      - name: table
        type: string
        description: "Table name"
      - name: filter
        type: string
        description: "PostgREST filter string (required)"
      - name: data
        type: object
        description: "Fields to update"
      - name: returning
        type: string
        optional: true
        description: "Columns to return"
    outputs:
      - name: result
        type: UpdateResult
        description: "Updated rows with count"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.supabaseDeleteRows:
    type: utility
    description: "Delete rows from a Supabase table matching a PostgREST filter condition."
    path: "supabase"
    domain_rules:
      - id: api_integration
        description: "Must call Supabase PostgREST DELETE /rest/v1/{table} with filter params and Prefer: return=representation"
    inputs:
      - name: table
        type: string
        description: "Table name"
      - name: filter
        type: string
        description: "PostgREST filter string (required)"
      - name: returning
        type: string
        optional: true
        description: "Columns to return"
    outputs:
      - name: result
        type: DeleteResult
        description: "Deleted rows with count"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.supabaseUpsertRows:
    type: utility
    description: "Insert or update rows in a Supabase table using merge-duplicates strategy."
    path: "supabase"
    domain_rules:
      - id: api_integration
        description: "Must call Supabase PostgREST POST /rest/v1/{table} with Prefer: resolution=merge-duplicates"
    inputs:
      - name: table
        type: string
        description: "Table name"
      - name: rows
        type: array
        description: "Array of row objects to upsert"
      - name: on_conflict
        type: string
        optional: true
        description: "Conflict resolution columns"
      - name: returning
        type: string
        optional: true
        description: "Columns to return"
    outputs:
      - name: result
        type: UpsertResult
        description: "Upserted rows with count"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.supabaseCallRpc:
    type: utility
    description: "Call a Supabase PostgreSQL function (RPC) with optional parameters."
    path: "supabase"
    domain_rules:
      - id: api_integration
        description: "Must call Supabase PostgREST POST /rest/v1/rpc/{function_name} endpoint"
    inputs:
      - name: function_name
        type: string
        description: "PostgreSQL function name"
      - name: params
        type: object
        optional: true
        description: "Function parameters"
    outputs:
      - name: result
        type: RpcResult
        description: "Function return value"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.supabaseCountRows:
    type: utility
    description: "Count rows in a Supabase table, optionally filtered by conditions."
    path: "supabase"
    domain_rules:
      - id: api_integration
        description: "Must call Supabase PostgREST HEAD /rest/v1/{table} with Prefer: count=exact and parse content-range header"
    inputs:
      - name: table
        type: string
        description: "Table name"
      - name: filter
        type: string
        optional: true
        description: "PostgREST filter string"
    outputs:
      - name: result
        type: CountResult
        description: "Row count and table name"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.supabaseListTables:
    type: utility
    description: "List all available tables in the Supabase database via the OpenAPI schema."
    path: "supabase"
    domain_rules:
      - id: api_integration
        description: "Must call Supabase PostgREST GET /rest/v1/ endpoint and extract table names from paths"
    inputs: []
    outputs:
      - name: result
        type: ListTablesResult
        description: "Sorted list of table names"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

  ops.supabaseSearchRows:
    type: utility
    description: "Search rows in a Supabase table by column+query pattern matching (ilike). Uses column and query inputs to build the ilike filter internally — no separate filter param needed."
    path: "supabase"
    domain_rules:
      - id: api_integration
        description: "Must call Supabase PostgREST GET /rest/v1/{table} with ilike.* filter built from column and query inputs"
    inputs:
      - name: table
        type: string
        description: "Table name to search"
      - name: column
        type: string
        description: "Column to apply ilike search on"
      - name: query
        type: string
        description: "Search term (wrapped in wildcards for contains matching)"
      - name: select
        type: string
        optional: true
        description: "Columns to select"
      - name: limit
        type: number
        optional: true
        description: "Maximum rows to return"
      - name: order
        type: string
        optional: true
        description: "Order by column(s)"
    outputs:
      - name: result
        type: SearchResult
        description: "Matching rows with count"
        measures: [working_implementation, valid_output_structure, proper_error_handling, ai_sdk_compliance]

# =============================================================================
# VALIDATORS - Which validators to run against each block
# =============================================================================
validators:
  - schema
  - shape.ts
  - domain