# Agent Tools

> Data tools for AI agents and developers behind one HTTP API and one MCP server: YouTube transcripts, open jobs from company careers pages, app store reviews, and X posts. Results are cached, so repeat requests are answered from the cache.

Base URL: https://api.openkrill.app (this page: https://tools.openkrill.app)

## Tools

Each tool has an HTTP name (used in the route) and an MCP name (used with tools/call).

- `yt-transcripts` (MCP: `get_transcript`): coming soon, not listed by `/v1/tools` or `tools/list` yet. The full transcript of one YouTube video, given a URL or an 11-character video ID. Output is timestamped segments (default), plain text, SRT or VTT. Optional `languages` in priority order and `translateTo`. A video without captions comes back as a result with status "error" and a code, not as an HTTP error. Cached for 30 days.
- `job-boards` (MCP: `list_jobs`): open jobs at companies on Greenhouse, Lever, Ashby, Workable or SmartRecruiters. Input is `companies`, careers page URLs or "ats:slug" tokens such as "greenhouse:airbnb". Optional filters: `keyword`, `location`, `remote`, `department`, `postedSince`, `maxJobsPerCompany`. A board that cannot be read comes back as a record of type "error". Cached for 1 hour.
- `app-reviews` (MCP: `get_app_reviews`): app metadata and recent reviews for Google Play and iOS App Store apps, given store URLs, Apple numeric ids or Play package names. Optional `countries`, `languages`, `maxReviewsPerApp`, `sinceDate` and `sort`. Apple's public review feed is sometimes empty; the result then holds the app row and an error row with code "unavailable". Cached for 6 hours.
- `x-posts` (MCP: `read_x_post`): X (Twitter) posts read without a login, given x.com, twitter.com, fxtwitter.com, fixupx.com or vxtwitter.com URLs or post ids (up to 20). Each post comes back as text, author, time, media URLs, the quoted post, reply target and public counts. Set `includeThread` to also get the author's own earlier posts in the thread, oldest first, up to 25. Replies from other accounts are not available because X serves them only to logged-in sessions; every post carries `replies.count` and `replies.available` false. Deleted, protected, suspended or age-restricted posts come back as a record of type "error" with a code. Only the posts you ask for are read, and nothing is kept past the cache time. Cached for 900 seconds (15 minutes).

## HTTP API

- `GET /v1/tools`: list the tools with their input schemas.
- `GET|POST /v1/tools/{name}/run`: run a tool. GET takes flat query parameters (repeat a key for arrays). POST takes a JSON body.
- `GET /v1/jobs/{id}`: result of a slow request that was answered with HTTP 202.
- `GET /v1/usage`: needs an API key. Billable items delivered to your API key this month, by charge event: reviews, jobs, and transcripts with status `ok`; error rows are free (`?period=YYYY-MM` for another month).

No API key is needed: a call without one runs as an anonymous caller, limited to 20 requests a minute and 200 tool calls a day per network (the day resets at 00:00 UTC). Past a limit the API answers HTTP 429 with `Retry-After` in seconds and an error that says how to lift it. An API key lifts those limits: send it as the `x-api-key` header, or as `Authorization: Bearer <key>` (60 requests a minute per key). A key that is wrong or disabled gets HTTP 401 and is never treated as anonymous. Keys come from support@openkrill.app.

Every run response carries `x-cache: HIT`, `MISS` or `STALE`, and a `Server-Timing` header. A request that takes longer than the server's wait budget is answered with HTTP 202, a job id and a poll URL while the work continues; the finished result is then served from the poll URL and from the cache. Rate limits are applied per network without a key and per API key with one, and answered with HTTP 429 and `Retry-After`.

Example:

```
curl "https://api.openkrill.app/v1/tools/job-boards/run?companies=greenhouse:airbnb&keyword=engineer&maxJobsPerCompany=5"
```

With a key, for higher limits:

```
curl -H "x-api-key: $KEY" "https://api.openkrill.app/v1/tools/job-boards/run?companies=greenhouse:airbnb&keyword=engineer&maxJobsPerCompany=5"
```

## MCP

Endpoint: https://api.openkrill.app/mcp (streamable HTTP, stateless: POST one JSON-RPC message or a short batch, get one JSON reply). Tools listed by `tools/list` today: `list_jobs`, `get_app_reviews`, `read_x_post` (`get_transcript` follows once YouTube transcripts are live). MCP calls wait for the result instead of returning a job id. No key is needed; the same anonymous limits apply, and the same optional API key header lifts them. A limit is reported as a tool error whose text starts with `rate_limited` or `anonymous_daily_limit`.

## Connect with OAuth

MCP clients that support OAuth (ChatGPT and Claude "Connect", or any client following the MCP authorization spec) can get an access token on their own; there is no key to create and no sign-in.

- MCP endpoint: https://connect.openkrill.app/mcp. Without a token it answers HTTP 401 with a `WWW-Authenticate` header that points to `https://connect.openkrill.app/.well-known/oauth-protected-resource/mcp`.
- Authorization server metadata: https://connect.openkrill.app/.well-known/oauth-authorization-server. It lists dynamic client registration (RFC 7591, `POST /oauth/register`), the authorization endpoint (authorization code with PKCE S256, approved automatically) and the token endpoint (refresh tokens rotate).
- Scope: `tools` (run the tools above); add `offline_access` for a refresh token.
- The access token also works as `Authorization: Bearer <token>` on https://api.openkrill.app/mcp and `/v1/tools/{name}/run`, with limits counted for your client.
- Registration and authorization are limited per network address; calls with a token are limited per client.

## ChatGPT plugins

Public MCP servers with no API key and no key option, one per plugin, for ChatGPT and other MCP clients. Calls are limited per network and per day; only aggregate call counts are kept (https://tools.openkrill.app/privacy).

- Company Jobs Finder: https://jobs.openkrill.app/mcp. One tool, `find_company_jobs`: open jobs at up to 5 named companies (names or careers page links) from Greenhouse, Lever, Ashby, Workable and SmartRecruiters, with `keyword`, `location`, `remote`, `department`, `postedSince` and `withSalary` filters. Read-only.
- Startup Name Check: https://names.openkrill.app/mcp. One tool, `check_domain_availability`: whether the domains for up to 5 names or domains are registered (RDAP, default endings com, net, org, ai, app, dev; `tlds` to choose others), with registration and expiry dates only and never owner details. Indicative, not a reservation; trademarks are not checked. Read-only.
- Package Health Check: https://packages.openkrill.app/mcp. Two tools: `check_package` (an npm or PyPI package, optionally at a version: known vulnerabilities with severity and fixed version from OSV.dev, license, deprecation notice, last release date, releases in the last year, dependents, weekly npm downloads) and `check_package_json` (the dependencies of a pasted package.json, up to 150, checked for known vulnerabilities; the file is not stored). Read-only.
- Recall Check: https://recalls.openkrill.app/mcp. Five tools: `check_vehicle_recalls` (year, make, model), `decode_vin`, `search_product_recalls` (CPSC consumer products), `search_food_drug_recalls` (FDA food and drug) and `search_pet_food_recalls`. US data only, not a safety guarantee. Read-only.
- Citation Checker: https://citations.openkrill.app/mcp. One tool, `check_references`: up to 10 references or DOIs at a time, each checked against Crossref, the DOI system (doi.org) and OpenAlex, with a verdict of found, mismatch or not_found and the paper's retraction status. Bibliographic details only. Read-only.
- Store Price Tracker: https://stores.openkrill.app/mcp. Two tools, `check_store_prices` and `get_product_price_history`: reads the public product feed (/products.json) of Shopify stores, up to 5 stores at a time, and reports products, prices, variants and availability plus new and removed products and price and stock changes since the previous daily snapshot. A store that is asked about is added to a daily snapshot list so product price history builds up. Honors robots.txt, identifies itself as StorePriceTracker and backs off when a store rate limits it. Public product data only.
- Business Days and Holidays: https://businessdays.openkrill.app/mcp. Three tools: `count_business_days` (working days between two dates for a country or region), `add_business_days` (the date a number of business days before or after a date) and `list_holidays` (public holidays from Nager.Date, school holidays from OpenHolidays). Each answer states how days were counted: weekend days, which holidays applied, and whether the start and end dates were included. Public holiday calendars only, not a legal deadline calculator. Read-only.
- Tariff Code Finder: https://tariffs.openkrill.app/mcp. Two tools: `find_tariff_codes` (candidate tariff codes for a described product, from the UK Trade Tariff or the US Harmonized Tariff Schedule) and `get_duty_rate` (the import duty on a code; for the UK also VAT, the preferential rate for an origin country and other measures). Every code is a candidate, not a binding classification; chapter 99 additional duties for the US are not included. UK and US only. Read-only.
- EU Business Check: https://eubusiness.openkrill.app/mcp. Three tools: `check_vat_number` (whether an EU or Northern Ireland VAT number is valid, with the registered name of a legal entity where the member state publishes it and a VIES consultation number on request), `find_company_lei` (the Legal Entity Identifier of a company, from GLEIF) and `lookup_company_registry` (the French Sirene and Norwegian Enhetsregisteret company registers). Names are shown only for legal entities; sole proprietors are left out. Read-only.
- Rules Lookup: https://rules.openkrill.app/mcp. Three tools: `get_cfr_section` (the current text, authority and amendment history of a section of the US Code of Federal Regulations, from the eCFR), `search_cfr` (which sections of the current regulations cover a topic) and `search_federal_register` (rules, proposed rules, notices and presidential documents, with comment deadlines and effective dates). General information, not legal advice; the eCFR is an unofficial edition; US federal regulations only. Read-only.
- Site Check: https://sitecheck.openkrill.app/mcp. Three tools: `check_ai_crawler_access` (whether a site's robots.txt, headers and redirects let 14 named AI crawlers fetch a page), `check_page_tags` (title, description, canonical, language, Open Graph and Twitter tags, and which are missing) and `trace_redirects` (each redirect hop, the final address, https upgrade and security headers). Only public http and https sites are fetched; private, local and internal addresses are refused, also after a redirect. Reports what a site declares, not a security scan or access control. Read-only.
- Travel Check: https://travel.openkrill.app/mcp. Three tools: `get_travel_advice` (a country by name or ISO code: UK FCDO alert and US State Department level with dates and links, optionally the UK entry-requirements, safety or health text), `get_airport_status` (FAA delays for US airports plus METAR and TAF weather, by IATA or ICAO code) and `compare_advisories` (up to 5 countries side by side). UK advice is for British citizens and US advice for US citizens. Not medical or safety advice, not for flight planning. Read-only.
- Food Facts: https://food.openkrill.app/mcp. Four tools: `lookup_barcode` (EAN or UPC barcode: ingredients, listed allergens, Nutri-Score, NOVA group, nutrition per 100 g, data-quality note), `search_products` (by name or brand, optionally a country), `compare_products` (up to 5 barcodes ranked by sugars, salt or kcal per 100 g) and `check_allergens` (the entry's listed allergens against ones to avoid). Data from Open Food Facts (ODbL), community-contributed: check the physical label. Not dietary or medical advice. Read-only.
- Car Check: https://cars.openkrill.app/mcp. Four tools: `decode_vin` (17-character VIN: year, make, model, trim, engine, with NHTSA's error codes), `get_vehicle_report` (VIN or year, make, model: NHTSA crash ratings, recall count, complaint count and top components, EPA fuel economy), `list_recalls` (year, make, model) and `get_fuel_economy` (EPA mpg or mpge, range, annual fuel cost). Data from NHTSA and the US EPA. US vehicles only; recalls and complaints are by model, not VIN; complaints are not confirmed defects. Not a valuation, history report or safety advice. Read-only.
- Document Tools: https://docs.openkrill.app/mcp. Three tools, `count_text`, `make_calendar_file` and `make_csv_file`: counts characters, words, sentences, SMS segments and reading time (text is never stored), and writes RFC 5545 calendar files and RFC 4180 CSV files as text plus a download link that works for 24 hours and is then deleted.
- Tax Numbers: https://tax.openkrill.app/mcp. Four tools, `get_tax_parameters`, `get_mileage_rate`, `tax_deadlines` and `estimate_federal_tax`: US federal tax figures for tax years 2025 and 2026 (brackets, standard deduction, long-term capital gains thresholds, Social Security wage base and self-employment tax, 401(k) and IRA limits), the IRS standard mileage rates since 2022, filing and estimated-payment deadlines, and a simple federal estimate with its assumptions and exclusions. Every row names the IRS document it comes from and every answer says when it was last verified. Estimates are not tax advice. Federal only; the amounts you give are never stored.
- Shop Duty Desk: https://shopduty.openkrill.app/mcp. Four tools: `eu_duty_estimate` (the 3 euros per item EU duty on consignments up to 150 euros, Regulations (EU) 2026/382 and 2026/1022, with the item count as given and with identical lines merged), `customs_data_gap_check` (a Shopify Inventory or product CSV checked for missing or malformed HS codes, origins, identifiers and barcodes), `bulk_hs_candidates` (candidate UK and US tariff codes for up to 20 product titles) and `landed_cost_estimate` (duty, VAT and total for a UK, US or EU destination). Every HS code is a candidate, not a binding classification. Order lines carry no customer data. No EU TARIC or Canada rates, no US chapter 99 duties. Read-only.
- Catalog QA Desk: https://catalogqa.openkrill.app/mcp. Four tools: `csv_import_preflight` (a Shopify product CSV checked before import, with blocking problems and warnings by row), `merchant_feed_check` (Google Merchant Center rules for barcodes, titles and descriptions), `listing_text_audit` (missing image alt text, copied and thin descriptions, title problems) and `listing_fix_sheet` (an advisory CSV of corrected alt text and titles). The last three take a CSV or a store domain; a domain is read once, from the public /products.json after robots.txt, identifying itself as CatalogQADesk, up to 1250 products. Large stores may block that feed, so a CSV is the dependable input. Nothing is stored, no personal data is read, and nothing is changed in the store. Read-only.

## Notes

- Error results (a blocked video, a missing job board, an unavailable Apple feed) are returned to the caller but never cached, so the next call retries.
- Reviews returned by `get_app_reviews` carry no reviewer identity.