{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Toolbelt",
    "description": "28 focused API tools for AI agents and developers: 8 LLM-powered stock research tools (investment thesis, earnings analysis, insider signals, valuation, bull/bear, comparison, moat, watchlist scan) plus 20 utility tools (data extraction, token counting, schema generation, contract clause extraction, prompt optimization, and more). Stock analysis $0.02/call; other rule-based tools from $0.0001/call. Free tier: 250 calls/month.",
    "version": "1.1.0",
    "contact": {
      "name": "Agent Toolbelt Support",
      "url": "https://www.agenttoolbelt.live"
    }
  },
  "servers": [
    {
      "url": "https://www.agenttoolbelt.live",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/tools/catalog": {
      "get": {
        "operationId": "getToolCatalog",
        "summary": "List all available tools",
        "description": "Returns the full catalog of available tools with descriptions, endpoints, and pricing. Use this to discover what tools are available before calling them.",
        "responses": {
          "200": {
            "description": "Tool catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tools": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "Tool identifier slug"
                          },
                          "description": {
                            "type": "string",
                            "description": "What the tool does"
                          },
                          "version": {
                            "type": "string"
                          },
                          "endpoint": {
                            "type": "string",
                            "description": "API endpoint path"
                          }
                        }
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/tools/schema-generator": {
      "post": {
        "operationId": "generateSchema",
        "summary": "Generate a data schema from a description",
        "description": "Generate JSON Schema, TypeScript interfaces, or Zod validation schemas from a natural language description of a data structure. Useful when you need to create or validate data models on the fly.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["description"],
                "properties": {
                  "description": {
                    "type": "string",
                    "description": "Natural language description of the data structure. Examples: 'a user profile with name, email, and signup date', 'a product listing with title, price, and inventory count', 'an event with start time, end time, and location'."
                  },
                  "format": {
                    "type": "string",
                    "enum": ["json_schema", "zod", "typescript"],
                    "default": "json_schema",
                    "description": "Output format. json_schema for standard JSON Schema, typescript for a TS interface, zod for a Zod validation schema."
                  },
                  "strict": {
                    "type": "boolean",
                    "default": true,
                    "description": "If true, all fields are required. If false, optional fields are marked as optional."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "tool": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "durationMs": {
                      "type": "integer",
                      "description": "Processing time in milliseconds"
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "schema": {
                          "description": "The generated schema (object for json_schema, string for typescript/zod)"
                        },
                        "format": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limit or quota exceeded"
          }
        }
      }
    },
    "/api/tools/text-extractor": {
      "post": {
        "operationId": "extractFromText",
        "summary": "Extract structured data from raw text",
        "description": "Extract emails, URLs, phone numbers, dates, currencies, addresses, names, or JSON blocks from unstructured text. Useful for parsing documents, emails, web content, or any raw text into structured data.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text", "extractors"],
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 10000,
                    "description": "The raw text to extract data from. Can be an email body, document content, web page text, chat transcript, etc."
                  },
                  "extractors": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "emails",
                        "urls",
                        "phone_numbers",
                        "dates",
                        "currencies",
                        "addresses",
                        "names",
                        "json_blocks"
                      ]
                    },
                    "minItems": 1,
                    "description": "Which types of data to extract from the text. Choose one or more."
                  },
                  "deduplicate": {
                    "type": "boolean",
                    "default": true,
                    "description": "If true, removes duplicate results within each extractor type."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "tool": {
                      "type": "string"
                    },
                    "durationMs": {
                      "type": "integer"
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "extracted": {
                          "type": "object",
                          "description": "Extracted data keyed by extractor type. Each value is an array of strings.",
                          "additionalProperties": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "totalItemsFound": {
                              "type": "integer"
                            },
                            "byType": {
                              "type": "object",
                              "additionalProperties": {
                                "type": "integer"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limit or quota exceeded"
          }
        }
      }
    },
    "/api/tools/cron-builder": {
      "post": {
        "operationId": "buildCronExpression",
        "summary": "Convert a schedule description into a cron expression",
        "description": "Convert natural language schedule descriptions into cron expressions. Returns the expression, human-readable confirmation, field breakdown, and next 5 scheduled run times.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["description"],
                "properties": {
                  "description": {
                    "type": "string",
                    "description": "Natural language schedule description. Examples: 'every weekday at 9am', 'first Monday of each month at noon', 'every 5 minutes', 'every Sunday at 3:30pm'."
                  },
                  "timezone": {
                    "type": "string",
                    "default": "UTC",
                    "description": "Timezone for context (e.g., 'America/New_York')."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Cron expression result" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/regex-builder": {
      "post": {
        "operationId": "buildRegex",
        "summary": "Build and test a regex from a description",
        "description": "Build regular expressions from natural language descriptions. Supports 20+ common patterns including emails, URLs, phone numbers, dates, IPs, hex colors, UUIDs, and more. Optionally test against provided strings. Returns pattern, code snippets in JS/Python/TS.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["description"],
                "properties": {
                  "description": {
                    "type": "string",
                    "description": "What to match. Examples: 'email addresses', 'US phone numbers', 'hex color codes', 'semantic version numbers'."
                  },
                  "testStrings": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Optional strings to test the regex against."
                  },
                  "flags": {
                    "type": "string",
                    "default": "g",
                    "description": "Regex flags (e.g., 'gi' for case-insensitive global)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Regex pattern and test results" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/address-normalizer": {
      "post": {
        "operationId": "normalizeAddress",
        "summary": "Normalize a US address to USPS format",
        "description": "Standardize US mailing addresses to USPS format. Expands abbreviations, corrects capitalization, standardizes street types and directionals, parses components (street number, name, unit, city, state, ZIP), and returns a confidence score.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["address"],
                "properties": {
                  "address": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "The address string to normalize. Examples: '123 main st apt 4b, springfield, il 62701', '456 N. Oak Avenue Suite 200, Los Angeles, CA 90210'."
                  },
                  "includeComponents": {
                    "type": "boolean",
                    "default": true,
                    "description": "Include parsed address components (streetNumber, streetName, streetType, city, state, ZIP, etc.) in the response."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Normalized address",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "tool": { "type": "string" },
                    "durationMs": { "type": "integer" },
                    "result": {
                      "type": "object",
                      "properties": {
                        "original": { "type": "string" },
                        "normalized": { "type": "string", "description": "USPS-formatted address" },
                        "confidence": { "type": "string", "enum": ["high", "medium", "low"] },
                        "components": {
                          "type": "object",
                          "properties": {
                            "streetNumber": { "type": "string" },
                            "preDirectional": { "type": "string" },
                            "streetName": { "type": "string" },
                            "streetType": { "type": "string" },
                            "postDirectional": { "type": "string" },
                            "secondaryUnit": { "type": "string" },
                            "secondaryNumber": { "type": "string" },
                            "city": { "type": "string" },
                            "state": { "type": "string" },
                            "zip": { "type": "string" },
                            "zip4": { "type": "string" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/csv-to-json": {
      "post": {
        "operationId": "csvToJson",
        "summary": "Convert CSV to JSON",
        "description": "Convert CSV data to typed JSON. Supports auto-delimiter detection (comma, semicolon, tab, pipe), header row parsing, type casting (numbers, booleans, nulls), column type inference, and row limits.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["csv"],
                "properties": {
                  "csv": {
                    "type": "string",
                    "maxLength": 500000,
                    "description": "CSV content to convert."
                  },
                  "delimiter": {
                    "type": "string",
                    "enum": ["auto", ",", ";", "\t", "|"],
                    "default": "auto",
                    "description": "Column delimiter. Use 'auto' to detect automatically."
                  },
                  "hasHeader": {
                    "type": "boolean",
                    "default": true,
                    "description": "Whether the first row is a header. If false, columns are named col_1, col_2, etc."
                  },
                  "typeCast": {
                    "type": "boolean",
                    "default": true,
                    "description": "Auto-convert values to numbers, booleans, and nulls where appropriate."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10000,
                    "description": "Maximum number of rows to return."
                  },
                  "skipEmptyRows": {
                    "type": "boolean",
                    "default": true,
                    "description": "Skip rows where all values are empty."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Converted JSON data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "tool": { "type": "string" },
                    "durationMs": { "type": "integer" },
                    "result": {
                      "type": "object",
                      "properties": {
                        "rows": { "type": "array", "items": { "type": "object" } },
                        "headers": { "type": "array", "items": { "type": "string" } },
                        "rowCount": { "type": "integer" },
                        "totalRows": { "type": "integer" },
                        "columnCount": { "type": "integer" },
                        "columnTypes": { "type": "object", "additionalProperties": { "type": "string" } },
                        "detectedDelimiter": { "type": "string" },
                        "truncated": { "type": "boolean" }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/token-counter": {
      "post": {
        "operationId": "countTokens",
        "summary": "Count tokens across LLM models",
        "description": "Count tokens for any text across multiple LLM models (GPT-4o, GPT-4, GPT-3.5, Claude 3.x, and more). Returns exact token counts using official tokenizers and estimated API costs per model.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 200000,
                    "description": "The text to count tokens for."
                  },
                  "models": {
                    "type": "array",
                    "items": { "type": "string" },
                    "default": ["gpt-4o", "claude-3-5-sonnet"],
                    "description": "Models to count tokens for. Supported: gpt-3.5-turbo, gpt-4, gpt-4-turbo, gpt-4o, gpt-4o-mini, claude-3-5-sonnet, claude-3-5-haiku, claude-3-opus, claude-3-sonnet, claude-3-haiku, claude-sonnet-4-6, claude-opus-4-6, text-embedding-ada-002, text-embedding-3-small, text-embedding-3-large."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token counts per model",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "tool": { "type": "string" },
                    "durationMs": { "type": "integer" },
                    "result": {
                      "type": "object",
                      "properties": {
                        "characterCount": { "type": "integer" },
                        "wordCount": { "type": "integer" },
                        "results": {
                          "type": "object",
                          "description": "Token count results keyed by model name.",
                          "additionalProperties": {
                            "type": "object",
                            "properties": {
                              "tokens": { "type": "integer" },
                              "encoding": { "type": "string" },
                              "approximate": { "type": "boolean" },
                              "estimatedCost": {
                                "type": "object",
                                "properties": {
                                  "input": { "type": "number", "description": "Estimated input cost in USD" },
                                  "output": { "type": "number", "description": "Estimated output cost in USD" },
                                  "currency": { "type": "string" }
                                }
                              }
                            }
                          }
                        },
                        "supportedModels": {
                          "type": "array",
                          "items": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/url-metadata": {
      "post": {
        "operationId": "fetchUrlMetadata",
        "summary": "Fetch metadata from a URL",
        "description": "Fetch a URL and extract metadata: title, description, Open Graph tags (og:image, og:type, etc.), Twitter card tags, favicon, canonical URL, author, and publish dates. Ideal for enriching links with context.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The URL to fetch metadata from."
                  },
                  "timeout": {
                    "type": "integer",
                    "minimum": 1000,
                    "maximum": 15000,
                    "default": 8000,
                    "description": "Request timeout in milliseconds (default 8000)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "URL metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "tool": { "type": "string" },
                    "durationMs": { "type": "integer" },
                    "result": {
                      "type": "object",
                      "properties": {
                        "url": { "type": "string" },
                        "finalUrl": { "type": "string", "description": "URL after redirects" },
                        "statusCode": { "type": "integer" },
                        "error": { "type": "string", "description": "Set if the fetch failed" },
                        "metadata": {
                          "type": "object",
                          "properties": {
                            "title": { "type": "string" },
                            "description": { "type": "string" },
                            "favicon": { "type": "string" },
                            "canonical": { "type": "string" },
                            "author": { "type": "string" },
                            "themeColor": { "type": "string" },
                            "publishedTime": { "type": "string" },
                            "modifiedTime": { "type": "string" },
                            "og": { "type": "object", "description": "All og: meta tags as key/value pairs", "additionalProperties": { "type": "string" } },
                            "twitter": { "type": "object", "description": "All twitter: meta tags as key/value pairs", "additionalProperties": { "type": "string" } }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/markdown-converter": {
      "post": {
        "operationId": "convertMarkdown",
        "summary": "Convert between HTML and Markdown",
        "description": "Convert HTML to clean Markdown or Markdown to HTML. Handles headings, lists, links, code blocks, tables, bold, italic, and more. Ideal for agents that need clean readable content from HTML pages, or need to render Markdown.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["content", "from", "to"],
                "properties": {
                  "content": {
                    "type": "string",
                    "maxLength": 100000,
                    "description": "The content to convert."
                  },
                  "from": {
                    "type": "string",
                    "enum": ["html", "markdown"],
                    "description": "Input format."
                  },
                  "to": {
                    "type": "string",
                    "enum": ["html", "markdown"],
                    "description": "Output format."
                  },
                  "options": {
                    "type": "object",
                    "description": "Optional conversion settings.",
                    "properties": {
                      "headingStyle": {
                        "type": "string",
                        "enum": ["atx", "setext"],
                        "default": "atx",
                        "description": "Heading style for Markdown output: atx uses #, setext uses underlines."
                      },
                      "bulletListMarker": {
                        "type": "string",
                        "enum": ["-", "*", "+"],
                        "default": "-",
                        "description": "Bullet list marker character."
                      },
                      "codeBlockStyle": {
                        "type": "string",
                        "enum": ["fenced", "indented"],
                        "default": "fenced",
                        "description": "Code block style in Markdown output."
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Converted content",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "tool": { "type": "string" },
                    "durationMs": { "type": "integer" },
                    "result": {
                      "type": "object",
                      "properties": {
                        "output": { "type": "string", "description": "Converted content" },
                        "from": { "type": "string" },
                        "to": { "type": "string" },
                        "inputLength": { "type": "integer" },
                        "outputLength": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/color-palette": {
      "post": {
        "operationId": "generateColorPalette",
        "summary": "Generate a color palette",
        "description": "Generate color palettes from a text description or a hex seed color. Returns colors with hex, RGB, and HSL values, WCAG contrast scores against white/black, and ready-to-use CSS custom properties. Supports 35+ aesthetic themes (calm, bold, earthy, neon, pastel, etc.) and complementary/analogous palette generation from a seed hex.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "description": {
                    "type": "string",
                    "description": "Text description of the desired palette. Examples: 'calm fintech blue', 'warm earthy tones', 'neon cyberpunk', 'pastel spring'. Use this or seedColor."
                  },
                  "seedColor": {
                    "type": "string",
                    "pattern": "^#[0-9A-Fa-f]{6}$",
                    "description": "Hex color to build the palette from (e.g. '#3B82F6'). Generates complementary and analogous colors."
                  },
                  "count": {
                    "type": "integer",
                    "minimum": 2,
                    "maximum": 10,
                    "default": 5,
                    "description": "Number of colors to return (2–10)."
                  },
                  "format": {
                    "type": "string",
                    "enum": ["hex", "rgb", "hsl", "all"],
                    "default": "all",
                    "description": "Color format in the output."
                  },
                  "includeShades": {
                    "type": "boolean",
                    "default": false,
                    "description": "If true, include light and dark shade variants for each color."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated color palette",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "tool": { "type": "string" },
                    "durationMs": { "type": "integer" },
                    "result": {
                      "type": "object",
                      "properties": {
                        "palette": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": { "type": "string" },
                              "hex": { "type": "string" },
                              "rgb": { "type": "object", "properties": { "r": { "type": "integer" }, "g": { "type": "integer" }, "b": { "type": "integer" } } },
                              "hsl": { "type": "object", "properties": { "h": { "type": "number" }, "s": { "type": "number" }, "l": { "type": "number" } } },
                              "wcag": {
                                "type": "object",
                                "properties": {
                                  "contrastWithWhite": { "type": "number" },
                                  "contrastWithBlack": { "type": "number" },
                                  "passesAA": { "type": "boolean" },
                                  "passesAAA": { "type": "boolean" }
                                }
                              },
                              "shades": {
                                "type": "object",
                                "properties": {
                                  "light": { "type": "string" },
                                  "dark": { "type": "string" }
                                }
                              }
                            }
                          }
                        },
                        "cssVariables": { "type": "string", "description": "CSS custom property declarations" },
                        "theme": { "type": "string", "description": "Detected or inferred palette theme" },
                        "count": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Validation error" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/brand-kit": {
      "post": {
        "operationId": "generateBrandKit",
        "summary": "Generate a complete brand kit",
        "description": "Generate a full brand kit from a company name, industry, and aesthetic keywords. Returns color palette (hex, HSL, RGB with WCAG accessibility scores), typography pairings (curated Google Fonts), and design tokens in JSON, CSS custom properties, or Tailwind config format. Powered by color psychology and professional design principles.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Company or brand name."
                  },
                  "industry": {
                    "type": "string",
                    "description": "Industry or sector (e.g., 'fintech', 'healthcare', 'fashion')."
                  },
                  "vibe": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Aesthetic keywords: 'modern', 'playful', 'luxurious', 'minimal', 'bold', 'organic', 'techy', 'warm', etc."
                  },
                  "targetAudience": {
                    "type": "string",
                    "description": "Who the brand is for."
                  },
                  "format": {
                    "type": "string",
                    "enum": ["full", "tokens", "css", "tailwind"],
                    "default": "full",
                    "description": "Output format: full (everything), tokens (JSON), css (custom properties), tailwind (config)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Generated brand kit" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/document-comparator": {
      "post": {
        "operationId": "compareDocuments",
        "summary": "Compare two document versions (semantic diff)",
        "description": "Compare two versions of any text document and produce a semantic diff. Returns additions, deletions, and modifications with significance ratings. Works with contracts, READMEs, policies, essays, or any text. Powered by Claude.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["original", "revised"],
                "properties": {
                  "original": { "type": "string", "description": "The original version of the document." },
                  "revised": { "type": "string", "description": "The revised version of the document." },
                  "mode": {
                    "type": "string",
                    "enum": ["summary", "detailed", "structured"],
                    "default": "structured",
                    "description": "'structured' returns categorized additions/deletions/modifications. 'detailed' returns prose analysis. 'summary' returns a brief overview."
                  },
                  "context": { "type": "string", "description": "Optional document type to improve analysis quality (e.g. 'employment contract', 'terms of service')." }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Document diff results" },
          "400": { "description": "Validation error" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/contract-clause-extractor": {
      "post": {
        "operationId": "extractContractClauses",
        "summary": "Extract key clauses from a contract",
        "description": "Extract and summarize key clauses from a contract or legal document. Identifies parties, payment terms, termination conditions, liability, IP ownership, confidentiality, and more. Optionally flags risky or one-sided clauses with severity ratings. Powered by Claude.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["contract"],
                "properties": {
                  "contract": { "type": "string", "description": "The contract or legal document text." },
                  "clauses": {
                    "type": "array",
                    "items": { "type": "string", "enum": ["parties", "dates", "payment_terms", "termination", "liability", "ip_ownership", "confidentiality", "governing_law", "penalties", "renewal", "warranties", "dispute_resolution"] },
                    "description": "Which clause types to extract. Defaults to all."
                  },
                  "flagRisks": { "type": "boolean", "default": true, "description": "Flag clauses that may be unfavorable or risky." }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Extracted clauses and risk analysis" },
          "400": { "description": "Validation error" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/prompt-optimizer": {
      "post": {
        "operationId": "optimizePrompt",
        "summary": "Analyze and improve an LLM prompt",
        "description": "Score an LLM prompt on clarity, specificity, structure, and completeness, then return an optimized rewrite with a summary of what changed and why. Supports targeting specific models for model-specific best practices.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "The LLM prompt to analyze and/or improve."
                  },
                  "model": {
                    "type": "string",
                    "default": "gpt-4o",
                    "description": "Target model to optimize for (e.g. 'gpt-4o', 'claude-3-5-sonnet', 'gpt-3.5-turbo')."
                  },
                  "task": {
                    "type": "string",
                    "description": "What this prompt is trying to accomplish. Helps generate more targeted suggestions."
                  },
                  "mode": {
                    "type": "string",
                    "enum": ["improve", "analyze", "both"],
                    "default": "both",
                    "description": "'both' returns analysis + improved prompt. 'analyze' returns scores and issues only. 'improve' returns rewritten prompt only."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Prompt analysis and/or optimized rewrite",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "tool": { "type": "string" },
                    "durationMs": { "type": "integer" },
                    "result": {
                      "type": "object",
                      "properties": {
                        "mode": { "type": "string" },
                        "model": { "type": "string" },
                        "scores": {
                          "type": "object",
                          "properties": {
                            "clarity": { "type": "number" },
                            "specificity": { "type": "number" },
                            "structure": { "type": "number" },
                            "completeness": { "type": "number" },
                            "overall": { "type": "number" }
                          }
                        },
                        "issues": { "type": "array", "items": { "type": "string" } },
                        "suggestions": { "type": "array", "items": { "type": "string" } },
                        "improvedPrompt": { "type": "string" },
                        "changesSummary": { "type": "array", "items": { "type": "string" } },
                        "tokenStats": {
                          "type": "object",
                          "properties": {
                            "original": { "type": "integer" },
                            "improved": { "type": "integer" },
                            "delta": { "type": "integer" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Validation error" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/meeting-action-items": {
      "post": {
        "operationId": "extractMeetingActionItems",
        "summary": "Extract action items from meeting notes",
        "description": "Parse meeting notes or transcripts and extract structured action items with owners, deadlines, and priorities. The 'full' format also returns a summary and list of key decisions. Powered by Claude.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["notes"],
                "properties": {
                  "notes": {
                    "type": "string",
                    "description": "Meeting notes or transcript (up to 50,000 characters)."
                  },
                  "format": {
                    "type": "string",
                    "enum": ["action_items_only", "full"],
                    "default": "full",
                    "description": "'full' returns action items + summary + decisions. 'action_items_only' returns just the task list."
                  },
                  "participants": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Known participant names to improve owner attribution (optional)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted action items and meeting analysis",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "tool": { "type": "string" },
                    "durationMs": { "type": "integer" },
                    "result": {
                      "type": "object",
                      "properties": {
                        "meetingTitle": { "type": "string" },
                        "actionItemCount": { "type": "integer" },
                        "actionItems": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": { "type": "integer" },
                              "owner": { "type": "string" },
                              "task": { "type": "string" },
                              "deadline": { "type": "string" },
                              "priority": { "type": "string", "enum": ["high", "medium", "low"] },
                              "context": { "type": "string" }
                            }
                          }
                        },
                        "summary": { "type": "string", "description": "Present when format=full" },
                        "decisions": {
                          "type": "array",
                          "items": { "type": "string" },
                          "description": "Present when format=full"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Validation error" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/image-metadata-stripper": {
      "post": {
        "operationId": "stripImageMetadata",
        "summary": "Strip EXIF/GPS/IPTC/XMP metadata from an image",
        "description": "Remove all embedded metadata from an image for privacy. Strips EXIF (camera settings, GPS coordinates, timestamps), IPTC (copyright, captions), XMP (editing history), and ICC color profiles. Accepts base64-encoded JPEG, PNG, WebP, or TIFF. Returns a cleaned base64 image with a report of what was removed and the file size reduction.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["image"],
                "properties": {
                  "image": {
                    "type": "string",
                    "description": "Base64-encoded image data (JPEG, PNG, WebP, or TIFF). Do not include the data URI prefix (e.g. 'data:image/jpeg;base64,')."
                  },
                  "format": {
                    "type": "string",
                    "enum": ["jpeg", "png", "webp", "preserve"],
                    "default": "preserve",
                    "description": "Output format. 'preserve' keeps the original image format."
                  },
                  "quality": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 90,
                    "description": "Output quality for lossy formats (JPEG, WebP). 1-100."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cleaned image with metadata removal report",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "tool": { "type": "string" },
                    "durationMs": { "type": "integer" },
                    "result": {
                      "type": "object",
                      "properties": {
                        "image": { "type": "string", "description": "Cleaned image as base64" },
                        "outputFormat": { "type": "string" },
                        "original": {
                          "type": "object",
                          "properties": {
                            "sizeBytes": { "type": "integer" },
                            "format": { "type": "string" },
                            "width": { "type": "integer" },
                            "height": { "type": "integer" },
                            "hasExif": { "type": "boolean" },
                            "hasIcc": { "type": "boolean" },
                            "hasIptc": { "type": "boolean" },
                            "hasXmp": { "type": "boolean" }
                          }
                        },
                        "output": {
                          "type": "object",
                          "properties": {
                            "sizeBytes": { "type": "integer" },
                            "reductionBytes": { "type": "integer" },
                            "reductionPercent": { "type": "number" }
                          }
                        },
                        "metadataStripped": { "type": "boolean" },
                        "strippedFields": {
                          "type": "array",
                          "items": { "type": "string" },
                          "description": "Human-readable list of metadata types that were removed"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid image data or unsupported format" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/api-response-mocker": {
      "post": {
        "operationId": "mockApiResponse",
        "summary": "Generate realistic mock API responses from a JSON Schema",
        "description": "Generate 1–100 realistic mock records from a JSON Schema. Supports nested objects, arrays, string formats (email, uuid, date-time, url, phone, ipv4), field-name heuristics (fields named 'email' get email addresses, 'createdAt' gets ISO timestamps, etc.), enums, and min/max constraints. Set seed for reproducible output. Perfect for test fixtures, dev database seeding, and prototype data.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["schema"],
                "properties": {
                  "schema": {
                    "type": "object",
                    "description": "JSON Schema object describing the shape of the mock data to generate.",
                    "example": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "string", "format": "uuid" },
                        "name": { "type": "string" },
                        "email": { "type": "string", "format": "email" },
                        "age": { "type": "integer", "minimum": 18, "maximum": 80 }
                      },
                      "required": ["id", "name", "email"]
                    }
                  },
                  "count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 1,
                    "description": "Number of mock records to generate (1–100)."
                  },
                  "seed": {
                    "type": "integer",
                    "description": "Optional seed for reproducible output. Same schema + same seed = same data."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Generated mock data matching the schema" },
          "400": { "description": "Invalid schema" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/context-window-packer": {
      "post": {
        "operationId": "packContextWindow",
        "summary": "Pack content chunks into a token budget",
        "description": "Intelligently select and pack content chunks to fit within a token budget. Three strategies: 'priority' (highest priority first), 'greedy' (input order), 'balanced' (most value-per-token). Returns packed chunks in original order, excluded chunks with reasons, the concatenated packed text, and token usage stats.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["chunks", "tokenBudget"],
                "properties": {
                  "chunks": {
                    "type": "array",
                    "description": "Content chunks to pack into the context window.",
                    "items": {
                      "type": "object",
                      "required": ["text"],
                      "properties": {
                        "text": { "type": "string", "description": "The content of this chunk." },
                        "label": { "type": "string", "description": "Optional identifier/label." },
                        "priority": { "type": "number", "minimum": 0, "maximum": 10, "default": 5, "description": "Importance score 0–10 (default 5)." },
                        "metadata": { "type": "object", "description": "Optional passthrough metadata." }
                      }
                    }
                  },
                  "tokenBudget": { "type": "integer", "description": "Maximum tokens allowed in the packed output." },
                  "model": { "type": "string", "default": "gpt-4o", "description": "Target model for tokenization (e.g. 'gpt-4o', 'claude-3-5-sonnet', 'gpt-4')." },
                  "strategy": { "type": "string", "enum": ["priority", "greedy", "balanced"], "default": "priority", "description": "Packing strategy." },
                  "separator": { "type": "string", "default": "\n\n", "description": "Text inserted between chunks. Counts toward budget." },
                  "systemPrompt": { "type": "string", "description": "System prompt to reserve tokens for (subtracted from budget before packing)." },
                  "reserveForOutput": { "type": "integer", "minimum": 0, "default": 0, "description": "Tokens to reserve for model output." }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Packed chunks, excluded chunks, and token stats" },
          "400": { "description": "Validation error" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/dependency-auditor": {
      "post": {
        "operationId": "auditDependencies",
        "summary": "Audit npm/PyPI packages for known CVEs",
        "description": "Check npm and PyPI packages for known security vulnerabilities using the OSV database (same source as GitHub Dependabot). Pass packages directly or paste raw package.json / requirements.txt content. Returns CVE IDs, severity (CRITICAL/HIGH/MODERATE/LOW), fixed versions, and advisory URLs per package, sorted by severity.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "packages": {
                    "type": "array",
                    "description": "Packages to audit.",
                    "items": {
                      "type": "object",
                      "required": ["name", "ecosystem"],
                      "properties": {
                        "name": { "type": "string", "description": "Package name." },
                        "version": { "type": "string", "description": "Version to check (e.g. '4.17.11'). Omit for all known vulns." },
                        "ecosystem": { "type": "string", "enum": ["npm", "pypi"], "description": "Package ecosystem." }
                      }
                    }
                  },
                  "manifest": { "type": "string", "description": "Raw package.json or requirements.txt content. Parsed automatically." },
                  "manifestType": { "type": "string", "enum": ["package.json", "requirements.txt", "auto"], "default": "auto" },
                  "includeDevDependencies": { "type": "boolean", "default": true, "description": "Include devDependencies when parsing package.json." },
                  "minSeverity": { "type": "string", "enum": ["LOW", "MODERATE", "HIGH", "CRITICAL"], "default": "LOW", "description": "Minimum severity to include in results." }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Vulnerability report with per-package details and summary" },
          "400": { "description": "Validation error" },
          "401": { "description": "Missing or invalid API key" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/tools/stock-thesis": {
      "post": {
        "operationId": "stockThesis",
        "summary": "Generate an investment thesis for a stock",
        "description": "Full Motley Fool-style investment thesis from live financial data: verdict (bullish/neutral/bearish), thesis paragraphs, key strengths, risks, valuation read, and what to watch next. Powered by Claude. $0.02/call.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["ticker"],
            "properties": {
              "ticker": { "type": "string", "description": "US-listed stock ticker (e.g. NVDA, AAPL, MSFT). US equities only." },
              "timeHorizon": { "type": "string", "enum": ["1-2 years", "3-5 years", "5+ years"], "default": "3-5 years", "description": "Investment time-horizon framing for the thesis." }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Investment thesis with verdict, strengths, risks, valuation, and watch-fors" },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "422": { "description": "Ticker is well-formed but has no data at any upstream provider (delisted, OTC, or non-US listing). Terminal — retrying will not help. Body carries the offending tickers and retryable=false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key" },
          "402": { "description": "Insufficient credits (PAYG)" },
          "429": { "description": "Rate limit, monthly quota, or stock per-minute limit exceeded" }
        }
      }
    },
    "/api/tools/earnings-analysis": {
      "post": {
        "operationId": "earningsAnalysis",
        "summary": "Analyze a stock's earnings track record",
        "description": "EPS beat/miss history (last 5 quarters), revenue trend, long-term read, and the upcoming earnings date. Powered by Claude. $0.02/call.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["ticker"],
            "properties": {
              "ticker": { "type": "string", "description": "US-listed stock ticker (e.g. NVDA, AAPL, MSFT). US equities only." }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Earnings track record, revenue trend, and next earnings date" },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key" },
          "402": { "description": "Insufficient credits (PAYG)" },
          "429": { "description": "Rate limit, monthly quota, or stock per-minute limit exceeded" }
        }
      }
    },
    "/api/tools/insider-signal": {
      "post": {
        "operationId": "insiderSignal",
        "summary": "Interpret insider trading activity",
        "description": "Reads Form 4 filings to distinguish meaningful open-market purchases from routine option-exercise noise. Returns a signal (strong_buy to strong_sell), confidence, and a plain-English verdict. Powered by Claude. $0.02/call.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["ticker"],
            "properties": {
              "ticker": { "type": "string", "description": "US-listed stock ticker (e.g. NVDA, AAPL, MSFT). US equities only." }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Insider signal, confidence, and interpretation" },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key" },
          "402": { "description": "Insufficient credits (PAYG)" },
          "429": { "description": "Rate limit, monthly quota, or stock per-minute limit exceeded" }
        }
      }
    },
    "/api/tools/valuation-snapshot": {
      "post": {
        "operationId": "valuationSnapshot",
        "summary": "Valuation snapshot with a verdict and buy zone",
        "description": "P/E, P/S, EV/EBITDA, FCF yield, and ROE synthesized into a verdict (very_cheap to very_expensive) plus a specific buy-zone price level. Includes a metricSources map showing which methodology backs each value. Powered by Claude. $0.02/call.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["ticker"],
            "properties": {
              "ticker": { "type": "string", "description": "US-listed stock ticker (e.g. NVDA, AAPL, MSFT). US equities only." }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Valuation metrics, verdict, and buy zone" },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "422": { "description": "Ticker is well-formed but has no data at any upstream provider (delisted, OTC, or non-US listing). Terminal — retrying will not help. Body carries the offending tickers and retryable=false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key" },
          "402": { "description": "Insufficient credits (PAYG)" },
          "429": { "description": "Rate limit, monthly quota, or stock per-minute limit exceeded" }
        }
      }
    },
    "/api/tools/bear-vs-bull": {
      "post": {
        "operationId": "bearVsBull",
        "summary": "Steelmanned bull vs. bear case for a stock",
        "description": "Three bull arguments and three bear arguments, each steelmanned with specific data, plus a net verdict, the key debate question, and who the stock suits. Powered by Claude. $0.02/call.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["ticker"],
            "properties": {
              "ticker": { "type": "string", "description": "US-listed stock ticker (e.g. NVDA, AAPL, MSFT). US equities only." }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Bull case, bear case, net verdict, and key debate" },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "422": { "description": "Ticker is well-formed but has no data at any upstream provider (delisted, OTC, or non-US listing). Terminal — retrying will not help. Body carries the offending tickers and retryable=false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key" },
          "402": { "description": "Insufficient credits (PAYG)" },
          "429": { "description": "Rate limit, monthly quota, or stock per-minute limit exceeded" }
        }
      }
    },
    "/api/tools/compare-stocks": {
      "post": {
        "operationId": "compareStocks",
        "summary": "Head-to-head comparison of 2-3 stocks",
        "description": "Compare 2-3 tickers on live valuation, quality, and growth metrics. Returns a winner verdict, per-ticker strengths/concerns, an ifYouValue map (growth/value/quality), and the key difference. Powered by Claude. $0.02/call.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["tickers"],
            "properties": {
              "tickers": { "type": "array", "minItems": 2, "maxItems": 3, "items": { "type": "string" }, "description": "2-3 US-listed tickers to compare (e.g. ['NVDA','AMD'])." }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Winner verdict with per-ticker breakdown" },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "422": { "description": "Ticker is well-formed but has no data at any upstream provider (delisted, OTC, or non-US listing). Terminal — retrying will not help. Body carries the offending tickers and retryable=false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key" },
          "402": { "description": "Insufficient credits (PAYG)" },
          "429": { "description": "Rate limit, monthly quota, or stock per-minute limit exceeded" }
        }
      }
    },
    "/api/tools/moat-analysis": {
      "post": {
        "operationId": "moatAnalysis",
        "summary": "Buffett-style competitive moat analysis",
        "description": "Rates a company's moat (wide/narrow/none), identifies moat sources (brand, switching costs, network effects, scale, intangibles/IP, cost advantage), and assesses durability and threats using ROIC, margins, and capex intensity. Powered by Claude. $0.02/call.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["ticker"],
            "properties": {
              "ticker": { "type": "string", "description": "US-listed stock ticker (e.g. NVDA, AAPL, MSFT). US equities only." }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Moat rating, sources, durability outlook, and threats" },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "422": { "description": "Ticker is well-formed but has no data at any upstream provider (delisted, OTC, or non-US listing). Terminal — retrying will not help. Body carries the offending tickers and retryable=false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key" },
          "402": { "description": "Insufficient credits (PAYG)" },
          "429": { "description": "Rate limit, monthly quota, or stock per-minute limit exceeded" }
        }
      }
    },
    "/api/tools/watchlist-scan": {
      "post": {
        "operationId": "watchlistScan",
        "summary": "Rank a watchlist of 2-15 stocks",
        "description": "Scan 2-15 tickers and rank them by a chosen lens (value, quality, growth, or income) in one call. Returns a ranked list with a one-line read per ticker, a top pick, the one to avoid, an overall takeaway, and the raw metrics. Powered by Claude. $0.05/call.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["tickers"],
            "properties": {
              "tickers": { "type": "array", "minItems": 2, "maxItems": 15, "items": { "type": "string" }, "description": "2-15 US-listed tickers to scan (e.g. ['NVDA','AMD','AVGO'])." },
              "focus": { "type": "string", "enum": ["value", "quality", "growth", "income"], "default": "value", "description": "Ranking lens: value (cheapest vs fundamentals), quality (best returns/margins), growth (fastest durable growth), or income (best sustainable dividend)." }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Ranked watchlist with top pick, one to avoid, and per-ticker reads" },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key" },
          "402": { "description": "Insufficient credits (PAYG)" },
          "429": { "description": "Rate limit, monthly quota, or stock per-minute limit exceeded" }
        }
      }
    },
    "/api/tools/portfolio-review": {
      "post": {
        "operationId": "portfolioReview",
        "summary": "Review a portfolio you already hold",
        "description": "Review 2-20 holdings as a portfolio rather than as screening candidates. Returns concentration risk (Herfindahl index, effective position count, largest position), sector exposure, weight-adjusted portfolio metrics (P/E, FCF yield, ROE, beta), correlated bets that share one underlying driver despite different sector labels, the weakest holding, trim candidates, and missing exposures. Powered by Claude. $0.05/call.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["holdings"],
            "properties": {
              "holdings": {
                "type": "array",
                "minItems": 2,
                "maxItems": 20,
                "description": "2-20 positions. Use weight on every holding, or shares on every holding, or neither for an equal-weighted portfolio. Mixing the two is a validation error.",
                "items": {
                  "type": "object",
                  "required": ["ticker"],
                  "properties": {
                    "ticker": { "type": "string", "description": "US-listed stock ticker (e.g. NVDA, AAPL). US equities only." },
                    "weight": { "type": "number", "exclusiveMinimum": 0, "description": "Position size in any consistent unit (percent, dollar value, or fraction). Weights are normalized internally, so they need not sum to 100." },
                    "shares": { "type": "number", "exclusiveMinimum": 0, "description": "Alternative to weight: share count, valued at the last close." }
                  }
                }
              }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Portfolio review with concentration, sector exposure, weighted metrics, overlapping bets, weakest link, trim candidates, and gaps" },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "422": { "description": "Fewer than 2 holdings had usable data (delisted, OTC, or non-US listings). Terminal — retrying will not help. Body carries the offending tickers and retryable=false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key" },
          "402": { "description": "Insufficient credits (PAYG)" },
          "429": { "description": "Rate limit, monthly quota, or stock per-minute limit exceeded" }
        }
      }
    },
    "/api/tools/web-summarizer": {
      "post": {
        "operationId": "summarizeWebPage",
        "summary": "Fetch a web page and summarize it",
        "description": "Fetch a URL, extract the main content as clean Markdown, and generate an AI summary with key points. Optionally focus the summary on a specific question or topic. Powered by Claude. $0.02/call.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["url"],
            "properties": {
              "url": { "type": "string", "description": "The URL to fetch and summarize." },
              "mode": { "type": "string", "enum": ["summary", "content", "both"], "default": "summary", "description": "Return an AI summary, the extracted Markdown content, or both." },
              "focus": { "type": "string", "description": "Optional question or topic to focus the summary on." },
              "maxContentLength": { "type": "integer", "description": "Optional cap on extracted content length (characters)." }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Summary and/or extracted content with key points" },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key" },
          "402": { "description": "Insufficient credits (PAYG)" },
          "429": { "description": "Rate limit or quota exceeded" }
        }
      }
    },
    "/api/watchlists": {
      "get": {
        "operationId": "listWatchlists",
        "summary": "List your saved watchlists",
        "description": "Returns the caller's saved watchlists, each with its tickers and whether it's monitored daily (Pro+ tiers).",
        "responses": {
          "200": { "description": "Array of watchlists" },
          "401": { "description": "Missing or invalid API key" }
        }
      },
      "post": {
        "operationId": "createWatchlist",
        "summary": "Create a saved watchlist",
        "description": "Save a named list of US tickers. On a Pro+ plan, watchlists are monitored daily and produce alerts (new insider buys, earnings within 7 days, big price moves). Tier limits cap the number of watchlists and tickers per list.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["name", "tickers"],
            "properties": {
              "name": { "type": "string", "description": "Name for the watchlist (max 100 chars)." },
              "tickers": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "US-listed tickers (e.g. [\"NVDA\",\"AMD\"]). Capped by tier." },
              "emailAlerts": { "type": "boolean", "default": true, "description": "Whether to email a digest when the watchlist changes (monitored tiers only)." }
            }
          } } }
        },
        "responses": {
          "201": { "description": "Created watchlist" },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key" },
          "403": { "description": "Watchlist limit reached for this tier" }
        }
      }
    },
    "/api/watchlists/{id}": {
      "parameters": [
        { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Watchlist id." }
      ],
      "get": {
        "operationId": "getWatchlist",
        "summary": "Get one saved watchlist",
        "responses": {
          "200": { "description": "The watchlist" },
          "401": { "description": "Missing or invalid API key" },
          "404": { "description": "Not found" }
        }
      },
      "patch": {
        "operationId": "updateWatchlist",
        "summary": "Update a saved watchlist",
        "description": "Update name, tickers, and/or emailAlerts. Any omitted field is left unchanged.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "tickers": { "type": "array", "items": { "type": "string" } },
              "emailAlerts": { "type": "boolean" }
            }
          } } }
        },
        "responses": {
          "200": { "description": "Updated watchlist" },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "401": { "description": "Missing or invalid API key" },
          "404": { "description": "Not found" }
        }
      },
      "delete": {
        "operationId": "deleteWatchlist",
        "summary": "Delete a saved watchlist",
        "responses": {
          "200": { "description": "Deleted" },
          "401": { "description": "Missing or invalid API key" },
          "404": { "description": "Not found" }
        }
      }
    },
    "/api/watchlists/{id}/alerts": {
      "parameters": [
        { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Watchlist id." }
      ],
      "get": {
        "operationId": "getWatchlistAlerts",
        "summary": "Recent monitor alerts for a watchlist",
        "description": "Recent change alerts (new insider buys, earnings within 7 days, big daily price moves) detected by the daily monitor. Pro+ only; returns an empty array (with an upgrade hint) on tiers without monitoring.",
        "responses": {
          "200": { "description": "Recent alerts (may be empty)" },
          "401": { "description": "Missing or invalid API key" },
          "404": { "description": "Not found" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error code"
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message"
          },
          "details": {
            "type": "object",
            "description": "Additional error details (for validation errors)"
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from Agent Toolbelt. Register at /api/clients/register to get a key. Pass as: Authorization: Bearer atb_..."
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}
