Skip to main content
Glama

Agent Tools API

by app.openkrill
OverviewDiscussionsAdmin

List jobs from company job boards

list_jobs
Read-onlyIdempotent

List open jobs at companies on Greenhouse, Lever, Ashby, Workable, SmartRecruiters, Workday, BambooHR, Personio, Recruitee, Breezy HR, Teamtailor, Oracle Recruiting Cloud, SAP SuccessFactors, Phenom, Eightfold, ADP, Paylocity, Cornerstone and 12 more hiring systems or 5 open job feeds from a careers URL, "ats:slug" (for example "greenhouse:airbnb", "workday:nvidia.wd5/NVIDIAExternalCareerSite") or a company name or domain (found on the first five ATS). Use when the user asks who is hiring, what roles a company has open, or to find remote or engineering roles at a named company. Optional filters: keyword, titleKeywords, excludeTitleKeywords, location, remote, department, employmentTypes, postedSince, postedWithinDays, withSalary. Returns normalized jobs (title, department, locations with ISO country codes, remote, workplace type, compensation, description, apply URL, dates); a board that cannot be read comes back as a type "error" record.

Input Schema

NameRequiredDescriptionDefault
remoteNoKeep only remote jobs when true
keywordNoKeep jobs whose title or description mentions every word of this text
locationNoKeep jobs whose location text or city contains this, or whose country matches this name or ISO code
maxItemsNoCap on jobs returned in total across all companies
companiesYesCareers page URLs, "ats:slug" tokens or company names and domains, e.g. ["greenhouse:airbnb", "https://jobs.lever.co/spotify", "https://nvidia.wd5.myworkdayjobs.com/NVIDIAExternalCareerSite", "stripe.com"]
departmentNoKeep jobs in a department matching this text
withSalaryNoKeep only jobs that publish a salary figure when true
postedSinceNoISO date; keep jobs posted or updated on or after it
titleKeywordsNoKeep jobs whose title contains any of these phrases, e.g. ["engineer", "developer"]
employmentTypesNoKeep jobs of these employment types
postedWithinDaysNoKeep jobs posted or updated in the last N days
maxJobsPerCompanyNoCap on jobs returned per company after filtering (default 1000)
includeDescriptionNoWorkday, SmartRecruiters and BambooHR need one extra request per job for the full text; false skips it for a faster list
excludeTitleKeywordsNoDrop jobs whose title contains any of these phrases, e.g. ["senior", "intern"]

Output Schema

NameRequiredDescriptionDefault
cacheYesHow the result was served: HIT or STALE from a cache tier, MISS or BYPASS when it was fetched now.
resultsYesOne row per open job, then one error row per company board that could not be read.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • changedInput schema / properties / companies / description
      Previous value: -"Careers page URLs or \"ats:slug\" tokens, e.g. [\"greenhouse:airbnb\", \"https://jobs.lever.co/spotify\"]"New value: +"Careers page URLs, \"ats:slug\" tokens or company names and domains, e.g. [\"greenhouse:airbnb\", \"https://jobs.lever.co/spotify\", \"https://nvidia.wd5.myworkdayjobs.com/NVIDIAExternalCareerSite\", \"stripe.com\"]"
    • addedInput schema / properties / employmentTypes
      Added value: +{
+  "description": "Keep jobs of these employment types",
+  "items": {
+    "enum": [
+      "full_time",
+      "part_time",
+      "contract",
+      "intern",
+      "temporary",
+      "other"
+    ],
+    "type": "string"
+  },
+  "maxItems": 6,
+  "type": "array"
+}
    • addedInput schema / properties / excludeTitleKeywords
      Added value: +{
+  "description": "Drop jobs whose title contains any of these phrases, e.g. [\"senior\", \"intern\"]",
+  "items": {
+    "maxLength": 100,
+    "type": "string"
+  },
+  "maxItems": 20,
+  "type": "array"
+}
    • addedInput schema / properties / includeDescription
      Added value: +{
+  "description": "Workday, SmartRecruiters and BambooHR need one extra request per job for the full text; false skips it for a faster list",
+  "type": "boolean"
+}
    • changedInput schema / properties / keyword / description
      Previous value: -"Keep jobs whose title or description mentions this text"New value: +"Keep jobs whose title or description mentions every word of this text"
    • addedInput schema / properties / maxItems
      Added value: +{
+  "description": "Cap on jobs returned in total across all companies",
+  "maximum": 5000,
+  "minimum": 1,
+  "type": "integer"
+}
    • addedInput schema / properties / postedWithinDays
      Added value: +{
+  "description": "Keep jobs posted or updated in the last N days",
+  "maximum": 365,
+  "minimum": 1,
+  "type": "integer"
+}
    • addedInput schema / properties / titleKeywords
      Added value: +{
+  "description": "Keep jobs whose title contains any of these phrases, e.g. [\"engineer\", \"developer\"]",
+  "items": {
+    "maxLength": 100,
+    "type": "string"
+  },
+  "maxItems": 20,
+  "type": "array"
+}
  2. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "cache": {
+      "description": "How the result was served: HIT or STALE from a cache tier, MISS or BYPASS when it was fetched now.",
+      "properties": {
+        "ageSeconds": {
+          "type": "number"
+        },
+        "source": {
+          "enum": [
+            "worker",
+            "origin",
+            "coalesced"
+          ],
+          "type": "string"
+        },
+        "status": {
+          "enum": [
+            "HIT",
+            "STALE",
+            "MISS",
+            "BYPASS"
+          ],
+          "type": "string"
+        },
+        "tier": {
+          "type": "string"
+        },
+        "ttlSeconds": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "status",
+        "tier",
+        "ageSeconds",
+        "ttlSeconds"
+      ],
+      "type": "object"
+    },
+    "results": {
+      "description": "One row per open job, then one error row per company board that could not be read.",
+      "items": {
+        "anyOf": [
+          {
+            "additionalProperties": true,
+            "properties": {
+              "applyUrl": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "ats": {
+                "type": "string"
+              },
+              "companyName": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "companySlug": {
+                "type": "string"
+              },
+              "compensation": {
+                "additionalProperties": true,
+                "type": [
+                  "object",
+                  "null"
+                ]
+              },
+              "department": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "id": {
+                "type": "string"
+              },
+              "locations": {
+                "items": {
+                  "additionalProperties": true,
+                  "properties": {
+                    "country": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    },
+                    "name": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "name"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "postedAt": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "remote": {
+                "type": [
+                  "boolean",
+                  "null"
+                ]
+              },
+              "sourceUrl": {
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "type": {
+                "const": "job"
+              },
+              "workplaceType": {
+                "enum": [
+                  "remote",
+                  "hybrid",
+                  "onsite",
+                  null
+                ],
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "type",
+              "id",
+              "ats",
+              "companySlug",
+              "title",
+              "locations",
+              "sourceUrl"
+            ],
+            "type": "object"
+          },
+          {
+            "additionalProperties": true,
+            "properties": {
+              "ats": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "code": {
+                "type": "string"
+              },
+              "companySlug": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "input": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "retryable": {
+                "type": "boolean"
+              },
+              "type": {
+                "const": "error"
+              }
+            },
+            "required": [
+              "type",
+              "input",
+              "code",
+              "message",
+              "retryable"
+            ],
+            "type": "object"
+          }
+        ]
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "results",
+    "cache"
+  ],
+  "type": "object"
+}
  3. First observed

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds real behavior: a board that cannot be read comes back as a type "error" record (partial-failure semantics), and includeDescription triggers one extra request per job for Workday/SmartRecruiters/BambooHR (cost tradeoff). Return shape is largely covered by the output schema, so 4 rather than 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the verb and resource, then scope, usage, filters, and return shape in three sentences. The 19-provider enumeration plus "and 12 more" is somewhat bloated, but it does communicate coverage breadth that an agent would otherwise have to guess.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter, single-required-field tool with a full output schema and annotations, the description covers scope, triggering intents, filter inventory, partial-failure behavior, and a per-source performance caveat. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents each filter, establishing a baseline of 3. The description earns extra credit by explaining the three accepted companies input forms and by flagging which ATS sources need the extra includeDescription request, which is semantic guidance the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (list) and resource (open jobs) and then pins down scope precisely: the supported ATS providers, the five job feeds from a careers URL, and the three accepted input forms ("ats:slug", URL, company name/domain). An agent immediately knows this is a job-board aggregator and not any of the review/feedback/transcript siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete triggering intents: "who is hiring", "what roles a company has open", "find remote or engineering roles at a named company". It also hints at filter usage via the optional-filters list. It does not name an alternative tool or state when not to use it, so it falls short of the explicit when/when-not bar.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Agent Tools API toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources