feat: add jsdoc comments to aiFunction impls

package.json

@@ -17,6 +17,7 @@
     "dev": "turbo dev --concurrency 50 --continue",
     "docs": "cd docs && npx mintlify dev",
     "clean": "turbo clean",
+    "fix:format": "prettier --write \"**/*.{js,ts,tsx}\"",
     "test": "turbo test",
     "test:format": "prettier --check \"**/*.{js,ts,tsx}\"",
     "test:lint": "turbo test:lint",

packages/apollo/src/apollo-client.ts

@@ -311,6 +311,13 @@ export class ApolloClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Attempts to enrich a person with Apollo data.
+   *
+   * Apollo relies on the information you pass via the endpoint's parameters to identify the correct person to enrich. If you provide more information about a person, Apollo is more likely to find a match within its database. If you only provide general information, such as a name without a domain or email address, you might receive a 200 response, but the response will indicate that no records have been enriched.
+   *
+   * By default, this endpoint does not return personal emails or phone numbers. Use the reveal_personal_emails and reveal_phone_number parameters to retrieve emails and phone numbers.
+   */
   @aiFunction({
     name: 'apollo_enrich_person',
     description: `Attempts to enrich a person with Apollo data.

packages/bing/src/bing-client.ts

@@ -275,6 +275,9 @@ export class BingClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Searches the web using the Bing search engine to return the most relevant web pages for a given query. Can also be used to find up-to-date news and information about many topics.
+   */
   @aiFunction({
     name: 'bing_web_search',
     description:

packages/dexa/src/dexa-client.ts

@@ -49,6 +49,9 @@ export class DexaClient extends AIFunctionsProvider {
     this.ky = ky.extend({ prefixUrl: this.apiBaseUrl, timeout: timeoutMs })
   }
 
+  /**
+   * Answers questions based on knowledge of trusted experts and podcasters. Example experts include: Andrew Huberman, Tim Ferriss, Lex Fridman, Peter Attia, Seth Godin, Rhonda Patrick, Rick Rubin, and more.
+   */
   @aiFunction({
     name: 'ask_dexa',
     description:

packages/dexa/src/scraper-client.ts

@@ -80,6 +80,9 @@ export class ScraperClient extends AIFunctionsProvider {
     this.ky = throttledKy.extend({ prefixUrl: this.apiBaseUrl })
   }
 
+  /**
+   * Scrapes the content of a single URL.
+   */
   @aiFunction({
     name: 'scrape_url',
     description: 'Scrapes the content of a single URL.',

packages/diffbot/src/diffbot-client.ts

@@ -661,6 +661,9 @@ export class DiffbotClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Scrapes and extracts structured data from a web page. Also classifies the web page as one of several types (article, product, discussion, job, image, video, list, event, or other).
+   */
   @aiFunction({
     name: 'diffbot_analyze_url',
     description:
@@ -673,6 +676,9 @@ export class DiffbotClient extends AIFunctionsProvider {
     return this._extract<diffbot.ExtractAnalyzeResponse>('v3/analyze', options)
   }
 
+  /**
+   * Scrapes and extracts clean article text from news articles, blog posts, and other text-heavy web pages.
+   */
   @aiFunction({
     name: 'diffbot_extract_article_from_url',
     description:
@@ -685,6 +691,9 @@ export class DiffbotClient extends AIFunctionsProvider {
     return this._extract<diffbot.ExtractArticleResponse>('v3/article', options)
   }
 
+  /**
+   * Resolves and enriches a partial person or organization entity.
+   */
   @aiFunction({
     name: 'diffbot_enhance_entity',
     description:

packages/firecrawl/src/firecrawl-client.ts

@@ -145,6 +145,9 @@ export class FirecrawlClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Scrape the contents of a URL.
+   */
   @aiFunction({
     name: 'firecrawl_scrape_url',
     description: 'Scrape the contents of a URL.',

packages/gravatar/src/gravatar-client.ts

@@ -160,6 +160,9 @@ export class GravatarClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Get Gravatar profile by email. Returns a profile object or `undefined` if not found.
+   */
   @aiFunction({
     name: 'gravatar_get_profile',
     description:

packages/hacker-news/src/hacker-news-client.ts

@@ -271,6 +271,7 @@ export class HackerNewsClient extends AIFunctionsProvider {
     })
   }
 
+  /** Fetches a HN story or comment by its ID. */
   @aiFunction({
     name: 'hacker_news_get_item',
     description: 'Fetches a HN story or comment by its ID.',
@@ -287,6 +288,9 @@ export class HackerNewsClient extends AIFunctionsProvider {
       .json<hackernews.SearchItem>()
   }
 
+  /**
+   * Fetches a HN user by username.
+   */
   @aiFunction({
     name: 'hacker_news_get_user',
     description: 'Fetches a HN user by username.',
@@ -303,6 +307,7 @@ export class HackerNewsClient extends AIFunctionsProvider {
       .json<hackernews.SearchUser>()
   }
 
+  /** Searches HN for stories and comments matching the given query. */
   @aiFunction({
     name: 'hacker_news_search',
     description:
@@ -342,6 +347,9 @@ export class HackerNewsClient extends AIFunctionsProvider {
       .json<hackernews.SearchResponse>()
   }
 
+  /**
+   * Fetches / searches the top stories currently on the front page of HN. This is the same as `hacker_news_search`, but with `tags: ["front_page"]` set to filter only by the current front page stories.
+   */
   @aiFunction({
     name: 'hacker_news_get_top_stories',
     description:

packages/hunter/src/hunter-client.ts

@@ -249,6 +249,9 @@ export class HunterClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Gets all the email addresses associated with a given company or domain.
+   */
   @aiFunction({
     name: 'hunter_domain_search',
     description:
@@ -280,6 +283,9 @@ export class HunterClient extends AIFunctionsProvider {
     return pruneNullOrUndefinedDeep(res)
   }
 
+  /**
+   * Finds the most likely email address from a domain name, a first name and a last name.
+   */
   @aiFunction({
     name: 'hunter_email_finder',
     description:
@@ -308,6 +314,9 @@ export class HunterClient extends AIFunctionsProvider {
     return pruneNullOrUndefinedDeep(res)
   }
 
+  /**
+   * Verifies the deliverability of an email address.
+   */
   @aiFunction({
     name: 'hunter_email_verifier',
     description: 'Verifies the deliverability of an email address.',

packages/jigsawstack/src/jigsawstack-client.ts

@@ -155,6 +155,9 @@ export class JigsawStackClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Perform web searches and retrieve high-quality results of the given query
+   */
   @aiFunction({
     name: 'jigsawstack_ai_search',
     description:
@@ -173,6 +176,9 @@ export class JigsawStackClient extends AIFunctionsProvider {
       .json<jigsawstack.SearchResponse>()
   }
 
+  /**
+   * Scrape any website
+   */
   @aiFunction({
     name: 'jigsawstack_ai_scrape',
     description: 'Scrape any website',
@@ -195,6 +201,9 @@ export class JigsawStackClient extends AIFunctionsProvider {
       .json<jigsawstack.ScrapeResponse>()
   }
 
+  /**
+   * Recognise, describe and retrieve data within an image with great accuracy.
+   */
   @aiFunction({
     name: 'jigsawstack_vocr',
     description:
@@ -217,6 +226,9 @@ export class JigsawStackClient extends AIFunctionsProvider {
       .json<jigsawstack.VOCRResponse>()
   }
 
+  /**
+   * Generate semantically correct SQL queries from text.
+   */
   @aiFunction({
     name: 'jigsawstack_text_to_sql',
     description: 'Generate semantically correct SQL queries from text.',
@@ -241,6 +253,9 @@ export class JigsawStackClient extends AIFunctionsProvider {
       .json<jigsawstack.TextToSqlResponse>()
   }
 
+  /**
+   * Convert audio/video files into accurate text transcriptions instantly.
+   */
   @aiFunction({
     name: 'jigsawstack_speech_to_text',
     description:

packages/jina/src/jina-client.ts

@@ -158,6 +158,9 @@ export class JinaClient extends AIFunctionsProvider {
     this.kySearch = throttledKySearch.extend({ prefixUrl: 'https://s.jina.ai' })
   }
 
+  /**
+   * Reads the contents of the given URL and returns it's main contents in a clean, LLM-friendly format.
+   */
   @aiFunction({
     name: 'readUrl',
     description:
@@ -198,6 +201,9 @@ export class JinaClient extends AIFunctionsProvider {
     }
   }
 
+  /**
+   * Searches the web for the given query and returns the top-5 results including their page contents in a clean, LLM-friendly format.
+   */
   @aiFunction({
     name: 'search',
     description:

packages/leadmagic/src/leadmagic-client.ts

@@ -97,6 +97,9 @@ export class LeadMagicClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Attempts to enrich a person with LeadMagic data based on their public LinkedIn username / identifier.
+   */
   @aiFunction({
     name: 'leadmagic_profile_search',
     description:

packages/midjourney/src/midjourney-client.ts

@@ -79,6 +79,9 @@ export class MidjourneyClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Creates 4 images from a prompt using the Midjourney API. Useful for generating images on the fly.
+   */
   @aiFunction({
     name: 'midjourney_create_images',
     description:

packages/predict-leads/src/predict-leads-client.ts

@@ -526,6 +526,9 @@ export class PredictLeadsClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Returns basic information about a company given its `domain` like location, name, stock ticker, description, etc.
+   */
   @aiFunction({
     name: 'get_company',
     description:
@@ -541,6 +544,9 @@ export class PredictLeadsClient extends AIFunctionsProvider {
     return this.ky.get(`v2/companies/${domain}`).json<predictleads.Response>()
   }
 
+  /**
+   * Returns a list of events from news for a given company. Events are found in press releases, industry news, blogs, social media, and other online sources.
+   */
   @aiFunction({
     name: 'get_company_events',
     description:

packages/proxycurl/src/proxycurl-client.ts

@@ -2108,6 +2108,7 @@ export class ProxycurlClient extends AIFunctionsProvider {
     })
   }
 
+  /** Gets the LinkedIn profile for a company given it's domain `url`. */
   @aiFunction({
     name: 'get_linkedin_company',
     description:
@@ -2134,6 +2135,7 @@ export class ProxycurlClient extends AIFunctionsProvider {
     }
   }
 
+  /** Gets the LinkedIn profile for a person given some unique, identifying information about them. */
   @aiFunction({
     name: 'get_linkedin_person',
     description:
@@ -2150,6 +2152,7 @@ export class ProxycurlClient extends AIFunctionsProvider {
       .json<proxycurl.PersonProfile>()
   }
 
+  /** Resolves the LinkedIn profile for a person given their `first_name` and `company_domain` URL. */
   @aiFunction({
     name: 'resolve_linkedin_person',
     description:
@@ -2170,6 +2173,7 @@ export class ProxycurlClient extends AIFunctionsProvider {
       .json<proxycurl.ResolvedPersonProfile>()
   }
 
+  /** Resolves the LinkedIn profile for a person given their `email`. */
   @aiFunction({
     name: 'resolve_linkedin_person_by_email',
     description:
@@ -2189,6 +2193,7 @@ export class ProxycurlClient extends AIFunctionsProvider {
       .json<proxycurl.ReverseEmailUrlEnrichResult>()
   }
 
+  /** Resolves the LinkedIn profile for a person at a given `company_name` and `role`. */
   @aiFunction({
     name: 'resolve_linkedin_person_at_company_by_role',
     description:
@@ -2208,6 +2213,7 @@ export class ProxycurlClient extends AIFunctionsProvider {
       .json<proxycurl.ResolvedPersonProfile>()
   }
 
+  /** Resolves the LinkedIn profile for a company given the `company_name` and/or `company_domain`. */
   @aiFunction({
     name: 'resolve_linkedin_company',
     description:
@@ -2232,6 +2238,7 @@ export class ProxycurlClient extends AIFunctionsProvider {
     }
   }
 
+  /** Searches LinkedIn company profiles based on a set of criteria such as `name`, `industry`, `region`, `description`, `city`, number of employees, founding date, funding raised, etc. */
   @aiFunction({
     name: 'search_linkedin_companies',
     description:
@@ -2246,6 +2253,7 @@ export class ProxycurlClient extends AIFunctionsProvider {
       .json<proxycurl.CompanySearchResult>()
   }
 
+  /** Searches LinkedIn people profiles based on a set of criteria such as `country`, `first_name`, `last_name`, `current_company_name`, `headline`, `industries`, `past_company_name`, `summary`, `city`, `education_school_name`, etc. */
   @aiFunction({
     name: 'search_linkedin_people',
     description:

packages/searxng/src/searxng-client.ts

@@ -307,6 +307,23 @@ export class SearxngClient extends AIFunctionsProvider {
     this.ky = ky.extend({ prefixUrl: apiBaseUrl })
   }
 
+  /**
+   * Searches across multiple search engines using a local instance of Searxng. To search only specific engines, use the `engines` parameter.
+   *
+   * The most important search engines are:
+   *
+   * - "reddit" (Reddit posts)
+   * - "google" (Google web search)
+   * - "google news" (Google News search)
+   * - "brave" (Brave web search)
+   * - "arxiv" (academic papers)
+   * - "genius" (Genius.com for song lyrics)
+   * - "imdb" (movies and TV shows)
+   * - "hackernews" (Hacker News)
+   * - "wikidata" (Wikidata)
+   * - "wolframalpha" (Wolfram Alpha)
+   * - "youtube" (YouTube videos)
+   */
   @aiFunction({
     name: 'searxng',
     description: `Searches across multiple search engines using a local instance of Searxng. To search only specific engines, use the \`engines\` parameter.

packages/serpapi/src/serpapi-client.ts

@@ -662,6 +662,9 @@ export class SerpAPIClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Uses Google Search to return the most relevant web pages for a given query. Useful for finding up-to-date news and information about any topic.
+   */
   @aiFunction({
     name: 'serpapi_google_search',
     description:

packages/serper/src/serper-client.ts

@@ -248,6 +248,9 @@ export class SerperClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Uses Google Search to return the most relevant web pages for a given query. Useful for finding up-to-date news and information about any topic.
+   */
   @aiFunction({
     name: 'serper_google_search',
     description:

packages/twitter/src/twitter-client.ts

@@ -176,6 +176,9 @@ export class TwitterClient extends AIFunctionsProvider {
   protected _findUserById: ReturnType<typeof findUserByIdImpl>
   protected _findUserByUsername: ReturnType<typeof findUserByUsernameImpl>
 
+  /**
+   * Creates a new tweet
+   */
   @aiFunction({
     name: 'create_tweet',
     description: 'Creates a new tweet',
@@ -189,6 +192,9 @@ export class TwitterClient extends AIFunctionsProvider {
     return this._createTweet(params)
   }
 
+  /**
+   * Fetch a tweet by its ID
+   */
   @aiFunction({
     name: 'get_tweet_by_id',
     description: 'Fetch a tweet by its ID',
@@ -196,18 +202,18 @@ export class TwitterClient extends AIFunctionsProvider {
       id: z.string().min(1)
     })
   })
-  async findTweetById({
-    id,
-    ...params
-  }: { id: string } & types.FindTweetByIdParams) {
+  async findTweetById(params: { id: string } & types.FindTweetByIdParams) {
     assert(
       this.twitterApiPlan !== 'free',
       'TwitterClient.findTweetById not supported on free plan'
     )
 
-    return this._findTweetById(id, params)
+    return this._findTweetById(params.id, params)
   }
 
+  /**
+   * Fetch an array of tweets by their IDs
+   */
   @aiFunction({
     name: 'get_tweets_by_id',
     description: 'Fetch an array of tweets by their IDs',
@@ -224,6 +230,9 @@ export class TwitterClient extends AIFunctionsProvider {
     return this._findTweetsById(ids, params)
   }
 
+  /**
+   * Searches for recent tweets
+   */
   @aiFunction({
     name: 'search_recent_tweets',
     description: 'Searches for recent tweets',
@@ -244,6 +253,9 @@ export class TwitterClient extends AIFunctionsProvider {
     return this._searchRecentTweets(params)
   }
 
+  /**
+   * Fetch a twitter user by ID
+   */
   @aiFunction({
     name: 'get_twitter_user_by_id',
     description: 'Fetch a twitter user by ID',
@@ -263,6 +275,9 @@ export class TwitterClient extends AIFunctionsProvider {
     return this._findUserById(id, params)
   }
 
+  /**
+   * Fetch a twitter user by username
+   */
   @aiFunction({
     name: 'get_twitter_user_by_username',
     description: 'Fetch a twitter user by username',

packages/weather/src/weather-client.ts

@@ -109,6 +109,9 @@ export class WeatherClient extends AIFunctionsProvider {
     this.ky = ky.extend({ prefixUrl: apiBaseUrl })
   }
 
+  /**
+   * Gets info about the current weather at a given location.
+   */
   @aiFunction({
     name: 'get_current_weather',
     description: 'Gets info about the current weather at a given location.',

packages/wikipedia/src/wikipedia-client.ts

@@ -139,6 +139,8 @@ export class WikipediaClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * Searches Wikipedia for pages matching the given query. */
   @aiFunction({
     name: 'wikipedia_search',
     description: 'Searches Wikipedia for pages matching the given query.',
@@ -157,6 +159,9 @@ export class WikipediaClient extends AIFunctionsProvider {
     )
   }
 
+  /**
+   * Gets a summary of the given Wikipedia page.
+   */
   @aiFunction({
     name: 'wikipedia_get_page_summary',
     description: 'Gets a summary of the given Wikipedia page.',

packages/wolfram-alpha/src/wolfram-alpha-client.ts

@@ -63,6 +63,10 @@ export class WolframAlphaClient extends AIFunctionsProvider {
     })
   }
 
+  /**
+   * WolframAlpha understands natural language queries about entities in chemistry, physics, geography, history, art, astronomy, and more.
+   * WolframAlpha performs mathematical calculations, date and unit conversions, formula solving, etc.
+   */
   @aiFunction({
     name: 'ask_wolfram_alpha',
     description: `