FoundRole — AI Job Search & Application Tracker MCP for Claude & ChatGPT
Server Details
MCP server for AI job search — find jobs, track applications, get alerts. Claude, ChatGPT, Cursor.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.3/5 across 15 of 15 tools scored. Lowest: 3.6/5.
Each tool has a clearly distinct purpose: alerts, jobs search/details, tracker CRUD, status updates, reminders, and external job addition. No significant overlap; tools like tracker_add and tracker_add_external are clearly separated by the source of the job.
All tools follow a consistent pattern: domain prefix (job_alert, jobs, reminder, tracker) followed by an underscore and a verb (list, subscribe, unsubscribe, details, search, etc.). Even 'jobs_details' uses 'details' as a verb, maintaining the pattern.
15 tools is well-scoped for a job search and application tracker. The number covers essential operations (search, view, track, alert, remind) without excess or deficiency.
The tool set covers the core lifecycle: searching jobs, viewing details, tracking jobs (CRUD plus status updates), setting reminders, and managing alerts. Missing explicit saved search management, but the core flow is complete and agents can work around minor gaps.
Available Tools
18 toolsjob_alert_listARead-onlyInspect
Lists the authenticated user's job alerts across all subscription sources (regular, company page, MCP).
Input:
status: Filter by status — one of pending, active, unsubscribed (optional, default: all statuses)limit: Number of results to return (default 20, max 50)offset: Number of results to skip (default 0)
Output: Returns the user's job alerts with pagination info and a summary of the underlying job search (query, location, company where available). Each response includes a system_instruction describing how to present the results for the current client.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results to return (default 20, max 50) | |
| offset | No | Number of results to skip (default 0) | |
| status | No | Filter by status: pending, active, unsubscribed |
Output Schema
| Name | Required | Description |
|---|---|---|
| hasMore | No | |
| jobAlerts | No | |
| totalCount | No | |
| frequencies | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds context about pagination, search summary, and a system_instruction for result presentation, which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the purpose, and uses clear section headers for Input and Output. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 3 optional parameters and an existing output schema, the description adequately covers pagination, search summary, and system_instruction. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds default values for all parameters (e.g., status defaults to all statuses), which is not in the schema. This provides meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Lists the authenticated user's job alerts across all subscription sources' with a specific verb and resource. It distinguishes from sibling tools like job_alert_subscribe, jobs_details, and tracker tools by focusing on listing alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The listing purpose implies use for viewing alerts, but no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
job_alert_subscribeAIdempotentInspect
Subscribes the authenticated user to job alerts for a specific saved job search.
Input:
job_search_id: The job search identifier to subscribe to (required). Accepts either the job search UUID or the composite job ID returned byjobs_search/jobs_details(format: "seo_id--job_search_id").frequency: Alert frequency — one of daily, weekly, monthly (optional, defaults to "weekly")
Output: Returns the created or updated job alert with id, status, and frequency. Idempotent: calling this tool for an already-subscribed search updates the existing alert without creating a duplicate.
| Name | Required | Description | Default |
|---|---|---|---|
| frequency | No | Alert frequency: daily, weekly, monthly (defaults to "weekly") | |
| job_search_id | Yes | Job search UUID or composite job id ("seo_id--job_search_id") from jobs_search results |
Output Schema
| Name | Required | Description |
|---|---|---|
| jobAlert | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses idempotent behavior ('updates existing alert without duplicate'), return structure (id, status, frequency), and mutation nature beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with clear Input/Output sections. Every sentence adds value, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: auth (authenticated user), input options, idempotency, output shape. No gaps given tool simplicity and output schema presence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100%, description adds clarity for job_search_id (accepts UUID or composite ID from jobs_search/jobs_details) and confirms frequency defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'subscribes' and resource 'job alerts for a specific saved job search'. Distinct from siblings like job_alert_list and job_alert_unsubscribe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on accepted input formats (UUID or composite ID) and idempotency. Does not explicitly exclude alternatives but context makes usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
job_alert_unsubscribeADestructiveInspect
Unsubscribes the authenticated user from job alerts for a specific job search.
Input:
job_search_id: The job search identifier to unsubscribe from (required). Accepts either the job search UUID or the composite job ID returned byjobs_search/jobs_details(format: "seo_id--job_search_id").
Output: Confirms the alert has been unsubscribed. Idempotent: returns success even when the user was not subscribed or is already unsubscribed.
| Name | Required | Description | Default |
|---|---|---|---|
| job_search_id | Yes | Job search UUID or composite job id ("seo_id--job_search_id") from jobs_search results |
Output Schema
| Name | Required | Description |
|---|---|---|
| message | No | |
| success | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds idempotency behavior ('returns success even when not subscribed') beyond the annotations (destructiveHint=true). This clarifies the non-error behavior on redundant calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with separate sections for Input and Output, and no extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description completes the picture by explaining input format and idempotency. It is sufficiently detailed for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the parameter job_search_id in detail, specifying that it accepts either a UUID or a composite ID from jobs_search/jobs_details with format hint. This adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'unsubscribes' and the resource 'job alerts for a specific job search'. It distinguishes itself from sibling tools like job_alert_subscribe and job_alert_list by focusing on the unsubscription action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives, such as job_alert_unsubscribe_all. It implies usage when unsubscribing from a specific job search, but lacks direct contrast with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
job_alert_unsubscribe_allADestructiveIdempotentInspect
Unsubscribes the authenticated user from ALL of their job alerts at once, across every subscription source (regular, company page, MCP).
Input:
confirm: Must betrueto execute. The call is rejected when omitted or not true — this guards against an unintended bulk unsubscribe.
Output: Confirms how many alerts were unsubscribed. Idempotent: returns success even when the user has no active alerts.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Set to true to confirm unsubscribing from every alert; the call is rejected otherwise |
Output Schema
| Name | Required | Description |
|---|---|---|
| message | No | |
| success | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds context about idempotency and the confirm guard beyond annotations, which already indicate destructive and idempotent hints. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with three clear paragraphs covering purpose, input, and output, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers behavior, input constraints, and output format. Could mention error cases or irreversibility, but sufficient for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds purpose of confirm parameter as a guard against unintended bulk unsubscribe, providing extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it unsubscribes from all job alerts across all subscription sources, using a specific verb and resource, and distinguishes from siblings like job_alert_unsubscribe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the confirm guard and idempotency but does not explicitly state when to use this tool versus single unsubscribe options, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
jobs_analyze_externalAInspect
Analyzes one job found outside FoundRole using the authenticated user's FoundRole profile and the same signals used for FoundRole jobs: resume match, missing skills, H-1B sponsorship history, E-Verify, ghost-job risk, posted compensation, and market salary estimates. Use tracker_add_external only when the user asks to save without analysis.
The input represents the direct posting URL and all job content already available in the conversation.
The five text identity fields and every structured field are required, with explicit null representing
a fact absent from the source. client_extraction carries evidence-backed skills, technology, benefits,
bonuses, seniority, industry, management, clearance, visa, and remote-scope labels. FoundRole validates
the evidence, stores the client extraction separately, derives missing deterministic facts, and reports
which values were provided, derived, accepted, rejected, or remain unknown.
The output includes comparisonRef; retain it exactly for a later jobs_compare call. The analysis is a
decision aid, not a guarantee about sponsorship, legitimacy, compensation, or hiring outcome.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Direct URL of the specific job posting; a company homepage is invalid | |
| posted_at | Yes | Posting date as ISO 8601, or null when the source does not state it | |
| title_name | Yes | Job title from the posting | |
| description | Yes | Complete posting text available in the conversation; a source summary is valid only when no fuller posting text is available | |
| salary_type | Yes | Salary period: year, month, week, day, hour, or null | |
| company_name | Yes | Company name from the posting | |
| salary_value | Yes | Single salary amount, or null when the posting gives a range or no salary | |
| location_name | Yes | Location text from the posting, including Remote when stated | |
| employment_type | Yes | Employment types: full_time, part_time, contractor, temporary, intern, volunteer, per_diem, other, or null | |
| salary_currency | Yes | ISO 4217 salary currency code, or null when not stated | |
| salary_max_value | Yes | Salary range maximum, or null when not stated | |
| salary_min_value | Yes | Salary range minimum, or null when not stated | |
| client_extraction | Yes | Evidence-backed facts extracted by the client model from the posting. Every nested field is present and nullable; non-null evidence is a short source excerpt rather than an inference. | |
| experience_months | Yes | Minimum required experience in months, or null when not stated | |
| work_location_type | Yes | Work arrangement: on_site, remote, hybrid, or null | |
| education_requirements | Yes | Education requirements: no_requirements, high_school, associate_degree, bachelor_degree, professional_certificate, postgraduate_degree, or null |
Output Schema
| Name | Required | Description |
|---|---|---|
| jobs | Yes | |
| mode | Yes | |
| statusOrder | Yes | |
| derivedFields | Yes | |
| trackerWebUrl | Yes | |
| unknownFields | Yes | |
| providedFields | Yes | |
| clientExtraction | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare non-read-only, non-destructive, and non-open-world. The description adds context: the analysis is a decision aid, not a guarantee; it explains the derivation process; and it mentions the output `comparisonRef`. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three well-organized paragraphs: first states purpose, second details input requirements and validation, third covers output and caveats. Every sentence adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (16 required params, nested objects, output schema), the description covers input, output, validation, and limitations. Minor omission of error or edge-case handling, but overall thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). The description adds significant meaning: explains that all fields are required with explicit nulls, details `client_extraction` structure and evidence-backed nature, and clarifies that the input includes conversation content. This goes well beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool analyzes an external job using the user's profile and specific signals (resume match, missing skills, H-1B, etc.). Distinguishes itself from sibling `tracker_add_external` by noting the latter is for saving without analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly contrasts with `tracker_add_external`, providing a clear when-to-use guideline. Lacks explicit when-not-to-use scenarios beyond the sibling note, but the context is sufficient for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
jobs_compareARead-onlyInspect
Compares 2 to 4 jobs side by side using the same FoundRole analysis fields: resume match, missing skills, H-1B and E-Verify signals, ghost-job risk, posted pay, and market salary estimates.
comparison_refs accepts exact FoundRole job IDs returned by jobs_search and exact external
comparisonRef URLs returned by jobs_analyze_external. Analyze each outside job first; a bare URL that
has not been analyzed cannot be compared because FoundRole does not have its posting facts. Preserve
every reference exactly, keep the user's requested order, and do not send duplicates.
| Name | Required | Description | Default |
|---|---|---|---|
| comparison_refs | Yes | Two to four exact FoundRole job IDs or external comparisonRef URLs |
Output Schema
| Name | Required | Description |
|---|---|---|
| jobs | Yes | |
| mode | Yes | |
| statusOrder | Yes | |
| trackerWebUrl | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds beyond these by detailing the prerequisite for external URLs and constraints (preserve order, no duplicates). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. First sentence front-loads the core purpose. Second paragraph is essential for usage rules. No fluff or repetition of schema/annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (covering return values), the description fully explains input constraints and behavior. It addresses prerequisites, ordering, and duplication, making it complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a basic description. The tool description adds significant semantic meaning: specifying exact ID/URL sources, requiring analysis first, preserving order, and avoiding duplicates. This goes beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states specific verb 'Compares' and resources '2 to 4 jobs side by side' with explicit analysis fields (resume match, missing skills, etc.). It clearly distinguishes from siblings like jobs_search (search) and jobs_analyze_external (single analysis).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on accepted inputs (FoundRole IDs or analyzed external comparisonRef URLs) and a prerequisite: external URLs must be analyzed first via jobs_analyze_external. It does not explicitly list alternatives but the context of comparison is unique among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
jobs_detailsAInspect
Fetches full details for one job by the id returned from jobs_search — the deeper view behind a search result.
Input:
job_id: The exact ID string from theidfield of ajobs_searchresult.
Output: Complete job details: description, skills, benefits, requirements, salary benchmark, resume match, H-1B and E-Verify signals, job-trust analysis, and application link. Personalized and extended insight fields follow the authenticated user's current entitlements.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The unique identifier of the job from jobs_search results |
Output Schema
| Name | Required | Description |
|---|---|---|
| job | No | |
| trackedJob | No | |
| statusOrder | No | |
| trackerWebUrl | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims 'Fetches full details' indicating a read-only operation, but annotation readOnlyHint=false suggests the tool may modify state. This is a direct contradiction. Additionally, no other behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a front-loaded purpose, followed by clear Input/Output sections. Every sentence adds value without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately outlines the output contents. However, the annotation contradiction leaves a gap in transparency about side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly defines job_id as 'the exact ID string from the id field of a jobs_search result', adding meaningful context beyond the schema's description. Schema coverage is 100% so the bar is high, but the description enhances clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Fetches full details for one job by the id returned from jobs_search', specifying verb (fetches), resource (full details for one job), and distinguishing from sibling jobs_search which returns search results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies that the job_id should come from jobs_search, providing clear usage context. However, it does not explicitly state when not to use this tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
jobs_recommendationsAIdempotentInspect
Returns the authenticated user's personalized job recommendations built from their resume, skills, target roles, and preferred location. Results are ranked by fit, may include related roles, and carry the same salary, match, H-1B, and job-trust insight payload used by job search.
A processing status means the personalized feed is still being prepared; a later call returns the completed feed. Page numbers fetch additional recommendations from the same feed.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Recommendation page number | |
| location | No | Optional preferred location name or slug |
Output Schema
| Name | Required | Description |
|---|---|---|
| jobs | No | |
| feedKind | No | |
| nextPage | No | |
| feedStatus | No | |
| totalCount | No | |
| statusOrder | No | |
| revalidating | No | |
| trackerWebUrl | No | |
| profileSetupUrl | No | |
| profileSetupState | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant context beyond annotations: mentions related roles, salary/match/H-1B/trust insights, and processing status behavior. No contradictions with annotations (idempotentHint=true, etc.).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs, no fluff. First paragraph states core function, second explains behavior. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a tool with output schema (payload details mentioned). Covers purpose, usage nuances, and pagination. No gaps given sibling tools and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. Description adds value by explaining pagination behavior of 'page' parameter beyond schema description. Location parameter not enhanced, but overall adds meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Returns' and clearly states resource: 'personalized job recommendations built from their resume, skills, target roles, and preferred location'. Clearly distinguishes from siblings like jobs_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on processing status and pagination ('A processing status means... a later call returns the completed feed. Page numbers fetch additional recommendations'). Does not explicitly mention alternatives but implied through sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
jobs_searchAInspect
Searches a database for real-time job listings matching the user's criteria.
The query is the full job title or role: "Ruby Developer" or "Ruby on Rails Engineer" rather than a bare keyword like "Ruby", which is too broad and matches unrelated fields. Results may be filtered by location, company, and how recently a job was posted.
Each result carries an id; jobs_details takes that id and returns the job's full description,
requirements, and benefits. The response also carries a nextCursor for the next page of
results; a follow-up page is fetched by passing only that cursor, with no other search parameters.
Authenticated results include resume match data when a profile is available. Job details include FoundRole salary benchmarks, H-1B sponsorship signals, E-Verify status, and job-trust analysis; list-level employer signals follow the user's current entitlements.
Each response includes a system_instruction describing how to present the results for the current client.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | The full job title or skill (e.g., "Ruby Developer", NOT just "Ruby") | |
| cursor | No | Pagination cursor. Treat as an opaque string. COPY EXACTLY. | |
| company | No | The official company name | |
| location | No | Geographic location (e.g., 'Boston, MA') | |
| posted_days_ago | No | Number of days ago to search for jobs (1-365) |
Output Schema
| Name | Required | Description |
|---|---|---|
| jobs | No | |
| feedKind | No | |
| feedStatus | No | |
| statusOrder | No | |
| revalidating | No | |
| trackerWebUrl | No | |
| profileSetupUrl | No | |
| profileSetupState | No | |
| lowRelevanceNotice | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds context about authenticated results including resume match data, employer signals based on entitlements, and pagination behavior. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer but well-structured, front-loading the core purpose. Each sentence adds meaningful information (query advice, filtering, result id usage, pagination, authentication, employer signals). No redundancy, though slight reduction possible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, annotations, output schema existence, and 15 sibling tools, the description covers all necessary aspects: tool purpose, usage context, parameter details, pagination, authentication effects, employer signals, and system instruction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% parameter description coverage. The description adds value beyond schema by advising on query format (full title vs keyword), explaining cursor as opaque string, and clarifying location format and posted_days_ago range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches a database for real-time job listings matching user criteria. It uses specific verbs ('Searches') and resource ('job listings'), and distinguishes from sibling tools like jobs_details (which takes an id for full description).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool (searching for jobs) and how to construct queries (full title, not bare keyword). It also mentions alternatives like jobs_details for full description and explains pagination with cursor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reminder_deleteADestructiveInspect
Deletes a reminder from a tracked job.
Input:
tracked_job_id: The tracked job ID —trackedJobs[].idfrom tracker_list output, distinct fromtrackable.idandjob.id(required)
Output: Returns the updated tracked job with reminderAt cleared.
| Name | Required | Description | Default |
|---|---|---|---|
| tracked_job_id | Yes | The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required) |
Output Schema
| Name | Required | Description |
|---|---|---|
| hasMore | No | |
| totalCount | No | |
| trackedJob | No | |
| statusOrder | No | |
| trackedJobs | No | |
| trackerWebUrl | No | |
| subStatusOrder | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds that it returns the updated tracked job with reminderAt cleared, providing behavioral context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one sentence for purpose, then labeled input/output sections. No wasted words, effective use of structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and output schema, the description covers the essentials. Could mention error cases, but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds semantic value by clarifying the ID is distinct from trackable.id and job.id, which goes beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it deletes a reminder from a tracked job. The verb 'deletes' is specific, and the tool is distinct from siblings like reminder_set and reminder_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deleting reminders, but does not explicitly state when to use or avoid this tool, nor compare it with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reminder_listARead-onlyInspect
Lists tracked jobs that have reminders set, ordered by reminder time (soonest first).
Input:
limit: Number of results to return (default 20, max 50)
Output: Returns a list of tracked jobs with active reminders.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results to return (default 20, max 50) |
Output Schema
| Name | Required | Description |
|---|---|---|
| hasMore | No | |
| totalCount | No | |
| trackedJobs | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable context: results are ordered by soonest reminder time and only include jobs with active reminders. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and well-structured, with a header, input section, and output section. It is front-loaded with the core purpose. Could be slightly more structured but no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not explain return values. Parameters are fully covered by schema. The tool is simple with one optional parameter and the description provides sufficient context for usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema description for the limit parameter matches the tool description. The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'lists' and the resource 'tracked jobs that have reminders set', with ordering by reminder time. It distinguishes from sibling tools like reminder_delete and tracker_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for what the tool does but does not explicitly mention when to use it versus alternatives like tracker_list or reminder_set. No exclusions or comparisons are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reminder_setADestructiveInspect
Sets a reminder for a tracked job. Sends a confirmation email with .ics calendar attachment.
Input:
tracked_job_id: The tracked job ID —trackedJobs[].idfrom tracker_list output, distinct fromtrackable.idandjob.id(required)remind_at: Reminder date/time in ISO 8601 format, e.g. "2025-03-15T10:00:00Z" (required, must be in the future)
Output: Returns the updated tracked job with reminderAt field.
| Name | Required | Description | Default |
|---|---|---|---|
| remind_at | Yes | ISO 8601 datetime, e.g. "2025-03-15T10:00:00Z" (must be in the future) | |
| tracked_job_id | Yes | The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required) |
Output Schema
| Name | Required | Description |
|---|---|---|
| hasMore | No | |
| totalCount | No | |
| trackedJob | No | |
| statusOrder | No | |
| trackedJobs | No | |
| trackerWebUrl | No | |
| subStatusOrder | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context: it sends an email with calendar attachment and returns the updated tracked job. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for input and output. It is concise, every sentence serves a purpose, and it avoids unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 required params, output schema exists), the description covers all necessary aspects: input details, output format, and side effects (email). It is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description repeats the schema descriptions verbatim. It adds no extra meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets a reminder for a tracked job and sends a confirmation email with an .ics attachment. It uses specific verbs and resource, and distinguishes from siblings like reminder_delete and reminder_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. While the context of sibling tools implies it for setting reminders, no direct guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tracker_addAInspect
Tracks a job from jobs_search results in the user's job tracker, identified by its job_id. For a job found elsewhere on the open web (with a URL but no jobs_search job_id), tracker_add_external is the right tool instead.
Fields:
job_id: the job ID from jobs_search results (required)status: initial status (saved, applied, interviewing, offered, archived); defaults to "saved"sub_status: sub-status within the main statusnotes: notes about the job
Returns the tracked job with its details. Repeated saves return the existing tracked job. A job that was previously removed from the tracker is restored with its earlier status and notes.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | Notes about this job | |
| job_id | Yes | The job ID from jobs.search results | |
| status | No | Initial tracking status: saved, applied, interviewing, offered, archived | |
| sub_status | No | Sub-status within the main status |
Output Schema
| Name | Required | Description |
|---|---|---|
| hasMore | No | |
| totalCount | No | |
| trackedJob | No | |
| statusOrder | No | |
| trackedJobs | No | |
| trackerWebUrl | No | |
| subStatusOrder | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that repeated saves return existing tracked job, and removed jobs are restored with earlier status/notes. This adds context beyond annotations (readOnlyHint=false, destructiveHint=false).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with main action, then lists parameters succinctly. No redundant sentences; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all relevant behaviors (repeated saves, restoration) and has output schema, so no need to describe return values. Complete for a tracking tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds default value for status and explains context for job_id, providing useful extra information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool tracks a job from jobs_search results by job_id, and distinguishes from tracker_add_external for external jobs. Verb 'tracks' is slightly vague but immediately clarified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool vs tracker_add_external: for jobs from jobs_search vs open web. Also explains behavior for repeated saves and restoration of removed jobs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tracker_add_externalAInspect
Saves a job posting found anywhere on the open web into the user's tracker. For jobs that came from jobs_search results, tracker_add (which takes a job_id) is the right tool instead. A job seen elsewhere in the conversation needs no prior jobs_search call — its URL and details from the conversation are sufficient input.
url, company_name, title_name, location_name, and description identify the posting.
The full job content available in the conversation forms the input. Every structured fact field
is required, with explicit null representing a fact absent from the source. client_extraction
carries evidence-backed skills, technology, benefits, bonuses, seniority, industry, management,
clearance, visa, and remote-scope labels. FoundRole validates and stores those labels separately;
missing canonical salary, employment, work-arrangement, education, experience, skills, benefits,
and bonuses are still derived by FoundRole's own extractors.
Fields:
url: the job posting's direct URL (required; not a company homepage)company_name: company nametitle_name: job titlelocation_name: location, e.g. "New York, NY"description: the posting's description from the source result; a short summary is acceptable (required)salary_min_value/salary_max_value: salary range bounds (numbers)salary_value: a single salary figure when there is no range (number)posted_at: ISO 8601 posting date or nullsalary_currency: ISO 4217 currency code or nullsalary_type: one of year, month, week, day, hour or nullemployment_type: array of full_time, part_time, contractor, temporary, intern, volunteer, per_diem, other or nullwork_location_type: one of on_site, remote, hybrid or nulleducation_requirements: array of no_requirements, high_school, associate_degree, bachelor_degree, professional_certificate, postgraduate_degree or nullexperience_months: minimum required experience in months (number)client_extraction: complete evidence-backed extraction object; every nested field is present and nullablestatus: initial tracking status (saved, applied, interviewing, offered, archived); defaults to "saved"sub_status: sub-status within the main statusnotes: notes about the job
Returns the tracked job. Repeated saves return the existing tracked job.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Direct URL of the specific job posting; a company homepage is invalid | |
| notes | No | Notes about this job | |
| status | No | Initial tracking status: saved, applied, interviewing, offered, archived | |
| posted_at | Yes | Posting date as ISO 8601, or null when the source does not state it | |
| sub_status | No | Sub-status within the main status | |
| title_name | Yes | Job title from the posting | |
| description | Yes | Complete posting text available in the conversation; a source summary is valid only when no fuller posting text is available | |
| salary_type | Yes | Salary period: year, month, week, day, hour, or null | |
| company_name | Yes | Company name from the posting | |
| salary_value | Yes | Single salary amount, or null when the posting gives a range or no salary | |
| location_name | Yes | Location text from the posting, including Remote when stated | |
| employment_type | Yes | Employment types: full_time, part_time, contractor, temporary, intern, volunteer, per_diem, other, or null | |
| salary_currency | Yes | ISO 4217 salary currency code, or null when not stated | |
| salary_max_value | Yes | Salary range maximum, or null when not stated | |
| salary_min_value | Yes | Salary range minimum, or null when not stated | |
| client_extraction | Yes | Evidence-backed facts extracted by the client model from the posting. Every nested field is present and nullable; non-null evidence is a short source excerpt rather than an inference. | |
| experience_months | Yes | Minimum required experience in months, or null when not stated | |
| work_location_type | Yes | Work arrangement: on_site, remote, hybrid, or null | |
| education_requirements | Yes | Education requirements: no_requirements, high_school, associate_degree, bachelor_degree, professional_certificate, postgraduate_degree, or null |
Output Schema
| Name | Required | Description |
|---|---|---|
| hasMore | No | |
| totalCount | No | |
| trackedJob | No | |
| statusOrder | No | |
| trackedJobs | No | |
| trackerWebUrl | No | |
| subStatusOrder | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that repeated saves return the existing tracked job (idempotent behavior) and explains the evidence-backed client_extraction. Annotations already indicate a write operation (readOnlyHint=false), but the description adds useful behavioral context beyond what annotations provide. However, it does not detail all potential side effects or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy due to detailed parameter explanations and examples. While it is front-loaded with purpose and usage, the parameter list largely repeats schema info with minor additions. It could be more concise without losing essential information, but the structure is logical and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (19 parameters, nested objects, required fields), the description covers purpose, usage guidelines, parameter semantics, behavioral traits, and return value. The output schema exists but description doesn't detail it, which is acceptable. All aspects needed for an agent to correctly invoke this tool are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters, so the baseline is 3. The description adds meaningful context beyond the schema, such as the requirement that 'url' must be a direct posting URL and that 'description' should be the full posting text. It also explains the structure and purpose of the complex 'client_extraction' object. However, some parameter details are redundant with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves a job posting from the open web into the user's tracker, using a specific verb and resource. It explicitly distinguishes the sibling tool tracker_add for jobs from jobs_search results, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: use tracker_add for jobs from jobs_search results, and tracker_add_external for jobs found elsewhere. It also clarifies that no prior jobs_search call is needed, giving clear when-to-use and when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tracker_listARead-onlyInspect
Lists the user's tracked jobs with optional filtering and pagination.
Input:
status: Filter by status (saved, applied, interviewing, offered, archived)limit: Number of results per page (default 20, max 50)offset: Number of results to skip (default 0)
Output: Returns a list of tracked jobs grouped by status with pagination info. Each response includes a system_instruction describing how to present the results for the current client.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results per page (default 20, max 50) | |
| offset | No | Number of results to skip (default 0) | |
| status | No | Filter by status: saved, applied, interviewing, offered, archived |
Output Schema
| Name | Required | Description |
|---|---|---|
| hasMore | No | |
| totalCount | No | |
| trackedJob | No | |
| statusOrder | No | |
| trackedJobs | No | |
| trackerWebUrl | No | |
| subStatusOrder | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive. Description adds value by disclosing output grouping by status and system_instruction for presentation, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sections (Input, Output) with no wasted words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists (implied) and annotations cover safety, description fully covers filtering, pagination, and output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. Description adds context about output grouping and pagination, enhancing understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists tracked jobs with filtering and pagination. Distinguishes from sibling tools like tracker_add or job_alert_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes input parameters and default values, implying usage for listing jobs. No explicit exclusions or alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tracker_removeADestructiveInspect
Removes a job from the user's job tracker.
Input:
tracked_job_id: The tracked job ID —trackedJobs[].idfrom tracker_list output, distinct fromtrackable.idandjob.id(required)
Output: Confirms the job was removed from tracking.
| Name | Required | Description | Default |
|---|---|---|---|
| tracked_job_id | Yes | The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required) |
Output Schema
| Name | Required | Description |
|---|---|---|
| hasMore | No | |
| totalCount | No | |
| trackedJob | No | |
| statusOrder | No | |
| trackedJobs | No | |
| trackerWebUrl | No | |
| subStatusOrder | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds context about the input ID's distinctness and the output format (confirmation of removal). This adds useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with one sentence and a bullet for input/output, front-loading the key information without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter destructive tool with output schema, the description adequately explains input source and output format, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description re-iterates the same text. It does not add new meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes a job from the tracker with a specific verb and resource. It is distinct from siblings like tracker_add and tracker_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly specify when to use this tool versus alternatives, but the action is clear from the name and context. No when-not-to-use or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tracker_updateADestructiveInspect
Updates details of a tracked job (notes, deadline, salary, tags).
Input:
tracked_job_id: The tracked job ID —trackedJobs[].idfrom tracker_list output, distinct fromtrackable.idandjob.id(required)notes: Updated notesdeadline: Deadline date (ISO 8601 format)salary_offered: Salary amountsalary_offered_type: Salary type: year, month, week, day, hourtags: Comma-separated tags (e.g., "remote,startup,tech")reminder_at: Reminder date/time in ISO 8601 format, e.g. "2025-03-15T10:00:00Z" (must be in the future, or empty to clear)
Output: Returns the updated tracked job.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Comma-separated tags (e.g., "remote,startup,tech") | |
| notes | No | Notes about this job | |
| deadline | No | Deadline date in ISO 8601 format | |
| reminder_at | No | ISO 8601 datetime, e.g. "2025-03-15T10:00:00Z" (must be in the future, or empty to clear) | |
| salary_offered | No | Salary amount | |
| tracked_job_id | Yes | The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required) | |
| salary_offered_type | No | Salary type: year, month, week, day, hour |
Output Schema
| Name | Required | Description |
|---|---|---|
| hasMore | No | |
| totalCount | No | |
| trackedJob | No | |
| statusOrder | No | |
| trackedJobs | No | |
| trackerWebUrl | No | |
| subStatusOrder | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint: true), the description adds valuable behavioral details: the correct ID source (trackedJobs[].id as distinct from other IDs), ISO 8601 format specifications, and the requirement that reminder_at must be in the future. These go beyond the schema and annotations to guide correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise with a clear structure: a one-line summary, a bullet list of parameters with explanations, and an output line. There is no extraneous information, though it could be slightly tighter by removing redundant formatting.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, output schema exists), the description is mostly complete. It covers all parameters, explains ID distinction and date constraints, and notes the return value. It lacks explicit statements about prerequisites (e.g., job must exist), but that is implied by the update action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description largely mirrors the schema's parameter descriptions without adding significant new meaning. Minor added context (e.g., 'distinct from traceable.id') is already present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Updates details of a tracked job (notes, deadline, salary, tags),' using a specific verb and resource. This sufficiently distinguishes it from sibling tools like tracker_add, tracker_remove, and tracker_update_status, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not provide explicit guidance on when to use it versus alternatives. Usage is implied by the parameter list, but no exclusion or reference to sibling tools is given, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tracker_update_statusADestructiveInspect
Updates the status of a tracked job.
Input:
tracked_job_id: The tracked job ID —trackedJobs[].idfrom tracker_list output, distinct fromtrackable.idandjob.id(required)status: New status: saved, applied, interviewing, offered, archived (required)sub_status: Sub-status within the main status (optional)
Output: Returns the updated tracked job.
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | New status: saved, applied, interviewing, offered, archived | |
| sub_status | No | Sub-status within the main status | |
| tracked_job_id | Yes | The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required) |
Output Schema
| Name | Required | Description |
|---|---|---|
| hasMore | No | |
| totalCount | No | |
| trackedJob | No | |
| statusOrder | No | |
| trackedJobs | No | |
| trackerWebUrl | No | |
| subStatusOrder | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, aligning with 'Updates'. The description adds no additional behavioral traits beyond the output mention. It does not disclose reversibility, error conditions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose. Input and output sections are clearly separated. However, it repeats some information from the schema, making it slightly redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status update, the description covers the key aspects: input parameters, output summary, and a distinguishing note on the ID. No output schema is provided, but the description mentions the return value, which is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by clarifying that 'tracked_job_id' is from tracker_list output and distinct from other IDs. This helps avoid confusion. Other parameters are not enhanced beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'Updates the status of a tracked job' with a specific verb and resource. While it doesn't explicitly differentiate from siblings like 'tracker_update', the name and focus on status provide sufficient clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the operation (updating status), but there is no explicit guidance on when to use this tool versus alternatives like 'tracker_update' or when not to use it. No prerequisites or context are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!