@tryfinch/finch-api-mcp 6.31.0 → 7.0.0

package/src/tools/hris/individuals/retrieve-many-hris-individuals.ts

@@ -1,21 +1,34 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { isJqError, maybeFilter } from '@tryfinch/finch-api-mcp/filtering';
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'hris.individuals',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/employer/individual',
+  operationId: 'get-individual',
 };
 
 export const tool: Tool = {
   name: 'retrieve_many_hris_individuals',
-  description: 'Read individual data, excluding income and employment data',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nRead individual data, excluding income and employment data\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    responses: {\n      type: 'array',\n      items: {\n        $ref: '#/$defs/individual_response'\n      }\n    }\n  },\n  required: [    'responses'\n  ],\n  $defs: {\n    individual_response: {\n      type: 'object',\n      properties: {\n        body: {\n          $ref: '#/$defs/individual'\n        },\n        code: {\n          type: 'integer'\n        },\n        individual_id: {\n          type: 'string'\n        }\n      },\n      required: [        'body',\n        'code',\n        'individual_id'\n      ]\n    },\n    individual: {\n      anyOf: [        {\n          type: 'object',\n          properties: {\n            id: {\n              type: 'string',\n              description: 'A stable Finch `id` (UUID v4) for an individual in the company.'\n            },\n            dob: {\n              type: 'string',\n              title: 'Date'\n            },\n            ethnicity: {\n              type: 'string',\n              description: 'The EEOC-defined ethnicity of the individual.',\n              enum: [                'asian',\n                'white',\n                'black_or_african_american',\n                'native_hawaiian_or_pacific_islander',\n                'american_indian_or_alaska_native',\n                'hispanic_or_latino',\n                'two_or_more_races',\n                'decline_to_specify'\n              ]\n            },\n            first_name: {\n              type: 'string',\n              description: 'The legal first name of the individual.'\n            },\n            gender: {\n              type: 'string',\n              description: 'The gender of the individual.',\n              enum: [                'female',\n                'male',\n                'other',\n                'decline_to_specify'\n              ]\n            },\n            last_name: {\n              type: 'string',\n              description: 'The legal last name of the individual.'\n            },\n            middle_name: {\n              type: 'string',\n              description: 'The legal middle name of the individual.'\n            },\n            phone_numbers: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  data: {\n                    type: 'string'\n                  },\n                  type: {\n                    type: 'string',\n                    enum: [                      'work',\n                      'personal'\n                    ]\n                  }\n                },\n                required: [                  'data',\n                  'type'\n                ]\n              }\n            },\n            preferred_name: {\n              type: 'string',\n              description: 'The preferred name of the individual.'\n            },\n            residence: {\n              $ref: '#/$defs/location'\n            },\n            emails: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  data: {\n                    type: 'string'\n                  },\n                  type: {\n                    type: 'string',\n                    enum: [                      'work',\n                      'personal'\n                    ]\n                  }\n                },\n                required: [                  'data',\n                  'type'\n                ]\n              }\n            },\n            encrypted_ssn: {\n              type: 'string',\n              description: 'Social Security Number of the individual in **encrypted** format. This field is only available with the `ssn` scope enabled and the `options: { include: [\\'ssn\\'] }` param set in the body.'\n            },\n            ssn: {\n              type: 'string',\n              description: 'Social Security Number of the individual. This field is only available with the `ssn` scope enabled and the `options: { include: [\\'ssn\\'] }` param set in the body. [Click here to learn more about enabling the SSN field](/developer-resources/Enable-SSN-Field).'\n            }\n          },\n          required: [            'id',\n            'dob',\n            'ethnicity',\n            'first_name',\n            'gender',\n            'last_name',\n            'middle_name',\n            'phone_numbers',\n            'preferred_name',\n            'residence'\n          ]\n        },\n        {\n          type: 'object',\n          properties: {\n            code: {\n              type: 'number'\n            },\n            message: {\n              type: 'string'\n            },\n            name: {\n              type: 'string'\n            },\n            finch_code: {\n              type: 'string'\n            }\n          },\n          required: [            'code',\n            'message',\n            'name'\n          ]\n        }\n      ]\n    },\n    location: {\n      type: 'object',\n      title: 'Location',\n      properties: {\n        city: {\n          type: 'string',\n          description: 'City, district, suburb, town, or village.'\n        },\n        country: {\n          type: 'string',\n          description: 'The 2-letter ISO 3166 country code.'\n        },\n        line1: {\n          type: 'string',\n          description: 'Street address or PO box.'\n        },\n        line2: {\n          type: 'string',\n          description: 'Apartment, suite, unit, or building.'\n        },\n        postal_code: {\n          type: 'string',\n          description: 'The postal code or zip code.'\n        },\n        state: {\n          type: 'string',\n          description: 'The state code.'\n        },\n        name: {\n          type: 'string'\n        },\n        source_id: {\n          type: 'string'\n        }\n      },\n      required: [        'city',\n        'country',\n        'line1',\n        'line2',\n        'postal_code',\n        'state'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
+      entity_ids: {
+        type: 'array',
+        description: "The entity IDs to specify which entities' data to access.",
+        items: {
+          type: 'string',
+        },
+      },
       options: {
         type: 'object',
         properties: {
@@ -26,7 +39,6 @@ export const tool: Tool = {
             },
           },
         },
-        required: [],
       },
       requests: {
         type: 'array',
@@ -37,16 +49,31 @@ export const tool: Tool = {
               type: 'string',
             },
           },
-          required: [],
         },
       },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
     },
+    required: [],
   },
+  annotations: {},
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.hris.individuals.retrieveMany(body);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  const response = await client.hris.individuals.retrieveMany(body).asResponse();
+  try {
+    return asTextContentResult(await maybeFilter(jq_filter, await response.json()));
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/hris/pay-statements/retrieve-many-hris-pay-statements.ts

@@ -1,13 +1,17 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'hris.pay_statements',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/employer/pay-statement',
+  operationId: 'get-pay-statement',
 };
 
 export const tool: Tool = {
@@ -39,13 +43,30 @@ export const tool: Tool = {
           required: ['payment_id'],
         },
       },
+      entity_ids: {
+        type: 'array',
+        description: "The entity IDs to specify which entities' data to access.",
+        items: {
+          type: 'string',
+        },
+      },
     },
+    required: ['requests'],
   },
+  annotations: {},
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.hris.payStatements.retrieveMany(body);
+  const response = await client.hris.payStatements.retrieveMany(body).asResponse();
+  try {
+    return asTextContentResult(await response.json());
+  } catch (error) {
+    if (error instanceof Finch.APIError) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/hris/payments/list-hris-payments.ts

@@ -1,18 +1,24 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { isJqError, maybeFilter } from '@tryfinch/finch-api-mcp/filtering';
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'hris.payments',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/payment',
+  operationId: 'get-payment',
 };
 
 export const tool: Tool = {
   name: 'list_hris_payments',
-  description: 'Read payroll and contractor related payments by the company.',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nRead payroll and contractor related payments by the company.\n\n# Response Schema\n```json\n{\n  type: 'array',\n  items: {\n    $ref: '#/$defs/payment'\n  },\n  $defs: {\n    payment: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'The unique id for the payment.'\n        },\n        company_debit: {\n          $ref: '#/$defs/money'\n        },\n        debit_date: {\n          type: 'string',\n          title: 'Date'\n        },\n        employee_taxes: {\n          $ref: '#/$defs/money'\n        },\n        employer_taxes: {\n          $ref: '#/$defs/money'\n        },\n        gross_pay: {\n          $ref: '#/$defs/money'\n        },\n        individual_ids: {\n          type: 'array',\n          description: 'Array of every individual on this payment.',\n          items: {\n            type: 'string'\n          }\n        },\n        net_pay: {\n          $ref: '#/$defs/money'\n        },\n        pay_date: {\n          type: 'string',\n          title: 'Date'\n        },\n        pay_frequencies: {\n          type: 'array',\n          description: 'List of pay frequencies associated with this payment.',\n          items: {\n            type: 'string',\n            enum: [              'annually',\n              'bi_weekly',\n              'daily',\n              'monthly',\n              'other',\n              'quarterly',\n              'semi_annually',\n              'semi_monthly',\n              'weekly'\n            ]\n          }\n        },\n        pay_group_ids: {\n          type: 'array',\n          description: 'Array of the Finch id (uuidv4) of every pay group associated with this payment.',\n          items: {\n            type: 'string'\n          }\n        },\n        pay_period: {\n          type: 'object',\n          description: 'The pay period object.',\n          properties: {\n            end_date: {\n              type: 'string',\n              title: 'Date'\n            },\n            start_date: {\n              type: 'string',\n              title: 'Date'\n            }\n          },\n          required: [            'end_date',\n            'start_date'\n          ]\n        }\n      },\n      required: [        'id',\n        'company_debit',\n        'debit_date',\n        'employee_taxes',\n        'employer_taxes',\n        'gross_pay',\n        'individual_ids',\n        'net_pay',\n        'pay_date',\n        'pay_frequencies',\n        'pay_group_ids',\n        'pay_period'\n      ]\n    },\n    money: {\n      type: 'object',\n      title: 'Money',\n      properties: {\n        amount: {\n          type: 'integer',\n          description: 'Amount for money object (in cents)'\n        },\n        currency: {\n          type: 'string'\n        }\n      },\n      required: [        'amount',\n        'currency'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -26,13 +32,38 @@ export const tool: Tool = {
         description: 'The start date to retrieve payments by a company (inclusive) in `YYYY-MM-DD` format.',
         format: 'date',
       },
+      entity_ids: {
+        type: 'array',
+        description: "The entity IDs to specify which entities' data to access.",
+        items: {
+          type: 'string',
+        },
+      },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
     },
+    required: ['end_date', 'start_date'],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.hris.payments.list(body);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  const response = await client.hris.payments.list(body).asResponse();
+  try {
+    return asTextContentResult(await maybeFilter(jq_filter, await response.json()));
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/index.ts

@@ -1,7 +1,8 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import Finch from '@tryfinch/finch-api';
-import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { Metadata, Endpoint, HandlerFunction } from './types';
+
+export { Metadata, Endpoint, HandlerFunction };
 
 import create_access_tokens from './access-tokens/create-access-tokens';
 import retrieve_hris_company from './hris/company/retrieve-hris-company';
@@ -11,7 +12,6 @@ import update_pay_statement_item_company_hris_rules from './hris/company/pay-sta
 import list_pay_statement_item_company_hris_rules from './hris/company/pay-statement-item/rules/list-pay-statement-item-company-hris-rules';
 import delete_pay_statement_item_company_hris_rules from './hris/company/pay-statement-item/rules/delete-pay-statement-item-company-hris-rules';
 import list_hris_directory from './hris/directory/list-hris-directory';
-import list_individuals_hris_directory from './hris/directory/list-individuals-hris-directory';
 import retrieve_many_hris_individuals from './hris/individuals/retrieve-many-hris-individuals';
 import retrieve_many_hris_employments from './hris/employments/retrieve-many-hris-employments';
 import list_hris_payments from './hris/payments/list-hris-payments';
@@ -51,20 +51,6 @@ import list_payroll_pay_groups from './payroll/pay-groups/list-payroll-pay-group
 import new_connect_sessions from './connect/sessions/new-connect-sessions';
 import reauthenticate_connect_sessions from './connect/sessions/reauthenticate-connect-sessions';
 
-export type HandlerFunction = (client: Finch, args: Record<string, unknown> | undefined) => Promise<any>;
-
-export type Metadata = {
-  resource: string;
-  operation: 'read' | 'write';
-  tags: string[];
-};
-
-export type Endpoint = {
-  metadata: Metadata;
-  tool: Tool;
-  handler: HandlerFunction;
-};
-
 export const endpoints: Endpoint[] = [];
 
 function addEndpoint(endpoint: Endpoint) {
@@ -79,7 +65,6 @@ addEndpoint(update_pay_statement_item_company_hris_rules);
 addEndpoint(list_pay_statement_item_company_hris_rules);
 addEndpoint(delete_pay_statement_item_company_hris_rules);
 addEndpoint(list_hris_directory);
-addEndpoint(list_individuals_hris_directory);
 addEndpoint(retrieve_many_hris_individuals);
 addEndpoint(retrieve_many_hris_employments);
 addEndpoint(list_hris_payments);
@@ -143,9 +128,10 @@ export function query(filters: Filter[], endpoints: Endpoint[]): Endpoint[] {
   });
 
   // Check if any filters didn't match
-  if (unmatchedFilters.size > 0) {
+  const unmatched = Array.from(unmatchedFilters).filter((f) => f.type === 'tool' || f.type === 'resource');
+  if (unmatched.length > 0) {
     throw new Error(
-      `The following filters did not match any endpoints: ${[...unmatchedFilters]
+      `The following filters did not match any endpoints: ${unmatched
         .map((f) => `${f.type}=${f.value}`)
         .join(', ')}`,
     );

package/src/tools/jobs/automated/create-jobs-automated.ts

@@ -1,19 +1,24 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { isJqError, maybeFilter } from '@tryfinch/finch-api-mcp/filtering';
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'jobs.automated',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/jobs/automated',
+  operationId: 'post-jobs-automated',
 };
 
 export const tool: Tool = {
   name: 'create_jobs_automated',
   description:
-    'Enqueue an automated job.\n\n`data_sync_all`: Enqueue a job to re-sync all data for a connection. `data_sync_all` has a concurrency limit of 1 job at a time per connection. This means that if this endpoint is called while a job is already in progress for this connection, Finch will return the `job_id` of the job that is currently in progress. Finch allows a fixed window rate limit of 1 forced refresh per hour per connection.\n\n`w4_form_employee_sync`: Enqueues a job for sync W-4 data for a particular individual, identified by `individual_id`. This feature is currently in beta.\n\nThis endpoint is available for *Scale* tier customers as an add-on. To request access to this endpoint, please contact your Finch account manager.',
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nEnqueue an automated job.\n\n`data_sync_all`: Enqueue a job to re-sync all data for a connection. `data_sync_all` has a concurrency limit of 1 job at a time per connection. This means that if this endpoint is called while a job is already in progress for this connection, Finch will return the `job_id` of the job that is currently in progress. Finch allows a fixed window rate limit of 1 forced refresh per hour per connection.\n\n`w4_form_employee_sync`: Enqueues a job for sync W-4 data for a particular individual, identified by `individual_id`. This feature is currently in beta.\n\nThis endpoint is available for *Scale* tier customers as an add-on. To request access to this endpoint, please contact your Finch account manager.\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/automated_create_response',\n  $defs: {\n    automated_create_response: {\n      type: 'object',\n      properties: {\n        allowed_refreshes: {\n          type: 'integer',\n          description: 'The number of allowed refreshes per hour (per hour, fixed window)'\n        },\n        remaining_refreshes: {\n          type: 'integer',\n          description: 'The number of remaining refreshes available (per hour, fixed window)'\n        },\n        job_id: {\n          type: 'string',\n          description: 'The id of the job that has been created.'\n        },\n        job_url: {\n          type: 'string',\n          description: 'The url that can be used to retrieve the job status'\n        },\n        retry_at: {\n          type: 'string',\n          description: 'ISO 8601 timestamp indicating when to retry the request'\n        }\n      },\n      required: [        'allowed_refreshes',\n        'remaining_refreshes'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     anyOf: [
@@ -26,6 +31,7 @@ export const tool: Tool = {
             enum: ['data_sync_all'],
           },
         },
+        required: ['type'],
       },
       {
         type: 'object',
@@ -46,14 +52,31 @@ export const tool: Tool = {
             enum: ['w4_form_employee_sync'],
           },
         },
+        required: ['params', 'type'],
       },
     ],
+    properties: {
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
+    },
   },
+  annotations: {},
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.jobs.automated.create(body);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(await maybeFilter(jq_filter, await client.jobs.automated.create(body)));
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/jobs/automated/list-jobs-automated.ts

@@ -1,19 +1,24 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { isJqError, maybeFilter } from '@tryfinch/finch-api-mcp/filtering';
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'jobs.automated',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/jobs/automated',
+  operationId: 'get-jobs-automated',
 };
 
 export const tool: Tool = {
   name: 'list_jobs_automated',
   description:
-    'Get all automated jobs. Automated jobs are completed by a machine. By default, jobs are sorted in descending order by submission time. For scheduled jobs such as data syncs, only the next scheduled job is shown.',
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nGet all automated jobs. Automated jobs are completed by a machine. By default, jobs are sorted in descending order by submission time. For scheduled jobs such as data syncs, only the next scheduled job is shown.\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/automated_list_response',\n  $defs: {\n    automated_list_response: {\n      type: 'object',\n      properties: {\n        data: {\n          type: 'array',\n          items: {\n            $ref: '#/$defs/automated_async_job'\n          }\n        },\n        meta: {\n          type: 'object',\n          properties: {\n            quotas: {\n              type: 'object',\n              description: 'Information about remaining quotas for this connection. Only applicable for customers opted in to use Finch\\'s Data Sync Refresh endpoint (`POST /jobs/automated`). Please contact a Finch representative for more details.',\n              properties: {\n                data_sync_all: {\n                  type: 'object',\n                  properties: {\n                    allowed_refreshes: {\n                      type: 'integer'\n                    },\n                    remaining_refreshes: {\n                      type: 'integer'\n                    }\n                  }\n                }\n              }\n            }\n          }\n        }\n      },\n      required: [        'data',\n        'meta'\n      ]\n    },\n    automated_async_job: {\n      type: 'object',\n      title: 'AutomatedAsyncJob',\n      properties: {\n        completed_at: {\n          type: 'string',\n          description: 'The datetime the job completed.',\n          format: 'date-time'\n        },\n        created_at: {\n          type: 'string',\n          description: 'The datetime when the job was created. for scheduled jobs, this will be the initial connection time. For ad-hoc jobs, this will be the time the creation request was received.',\n          format: 'date-time'\n        },\n        job_id: {\n          type: 'string',\n          description: 'The id of the job that has been created.'\n        },\n        job_url: {\n          type: 'string',\n          description: 'The url that can be used to retrieve the job status'\n        },\n        params: {\n          type: 'object',\n          description: 'The input parameters for the job.',\n          properties: {\n            individual_id: {\n              type: 'string',\n              description: 'The ID of the individual that the job was completed for.'\n            }\n          }\n        },\n        scheduled_at: {\n          type: 'string',\n          description: 'The datetime a job is scheduled to be run. For scheduled jobs, this datetime can be in the future if the job has not yet been enqueued. For ad-hoc jobs, this field will be null.',\n          format: 'date-time'\n        },\n        started_at: {\n          type: 'string',\n          description: 'The datetime a job entered into the job queue.',\n          format: 'date-time'\n        },\n        status: {\n          type: 'string',\n          enum: [            'pending',\n            'in_progress',\n            'complete',\n            'error',\n            'reauth_error',\n            'permissions_error'\n          ]\n        },\n        type: {\n          type: 'string',\n          description: 'The type of automated job',\n          enum: [            'data_sync_all',\n            'w4_form_employee_sync'\n          ]\n        }\n      },\n      required: [        'completed_at',\n        'created_at',\n        'job_id',\n        'job_url',\n        'params',\n        'scheduled_at',\n        'started_at',\n        'status',\n        'type'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -25,13 +30,30 @@ export const tool: Tool = {
         type: 'integer',
         description: 'Index to start from (defaults to 0)',
       },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
     },
+    required: [],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.jobs.automated.list(body);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(await maybeFilter(jq_filter, await client.jobs.automated.list(body)));
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/jobs/automated/retrieve-jobs-automated.ts

@@ -1,31 +1,54 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { isJqError, maybeFilter } from '@tryfinch/finch-api-mcp/filtering';
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'jobs.automated',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/jobs/automated/{job_id}',
+  operationId: 'get-jobs-job_id',
 };
 
 export const tool: Tool = {
   name: 'retrieve_jobs_automated',
-  description: 'Get an automated job by `job_id`.',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nGet an automated job by `job_id`.\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/automated_async_job',\n  $defs: {\n    automated_async_job: {\n      type: 'object',\n      title: 'AutomatedAsyncJob',\n      properties: {\n        completed_at: {\n          type: 'string',\n          description: 'The datetime the job completed.',\n          format: 'date-time'\n        },\n        created_at: {\n          type: 'string',\n          description: 'The datetime when the job was created. for scheduled jobs, this will be the initial connection time. For ad-hoc jobs, this will be the time the creation request was received.',\n          format: 'date-time'\n        },\n        job_id: {\n          type: 'string',\n          description: 'The id of the job that has been created.'\n        },\n        job_url: {\n          type: 'string',\n          description: 'The url that can be used to retrieve the job status'\n        },\n        params: {\n          type: 'object',\n          description: 'The input parameters for the job.',\n          properties: {\n            individual_id: {\n              type: 'string',\n              description: 'The ID of the individual that the job was completed for.'\n            }\n          }\n        },\n        scheduled_at: {\n          type: 'string',\n          description: 'The datetime a job is scheduled to be run. For scheduled jobs, this datetime can be in the future if the job has not yet been enqueued. For ad-hoc jobs, this field will be null.',\n          format: 'date-time'\n        },\n        started_at: {\n          type: 'string',\n          description: 'The datetime a job entered into the job queue.',\n          format: 'date-time'\n        },\n        status: {\n          type: 'string',\n          enum: [            'pending',\n            'in_progress',\n            'complete',\n            'error',\n            'reauth_error',\n            'permissions_error'\n          ]\n        },\n        type: {\n          type: 'string',\n          description: 'The type of automated job',\n          enum: [            'data_sync_all',\n            'w4_form_employee_sync'\n          ]\n        }\n      },\n      required: [        'completed_at',\n        'created_at',\n        'job_id',\n        'job_url',\n        'params',\n        'scheduled_at',\n        'started_at',\n        'status',\n        'type'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
       job_id: {
         type: 'string',
       },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
     },
+    required: ['job_id'],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const { job_id, ...body } = args as any;
-  return client.jobs.automated.retrieve(job_id);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { job_id, jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(await maybeFilter(jq_filter, await client.jobs.automated.retrieve(job_id)));
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/jobs/manual/retrieve-jobs-manual.ts

@@ -1,32 +1,54 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { isJqError, maybeFilter } from '@tryfinch/finch-api-mcp/filtering';
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'jobs.manual',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/jobs/manual/{job_id}',
+  operationId: 'get-jobs-manual-job_id',
 };
 
 export const tool: Tool = {
   name: 'retrieve_jobs_manual',
   description:
-    'Get a manual job by `job_id`. Manual jobs are completed by a human and include Assisted Benefits jobs.',
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nGet a manual job by `job_id`. Manual jobs are completed by a human and include Assisted Benefits jobs.\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/manual_async_job',\n  $defs: {\n    manual_async_job: {\n      type: 'object',\n      title: 'ManualAsyncJob',\n      properties: {\n        body: {\n          type: 'array',\n          description: 'Specific information about the job, such as individual statuses for batch jobs.',\n          items: {\n            type: 'object',\n            additionalProperties: true\n          }\n        },\n        job_id: {\n          type: 'string'\n        },\n        status: {\n          type: 'string',\n          enum: [            'pending',\n            'in_progress',\n            'error',\n            'complete'\n          ]\n        }\n      },\n      required: [        'body',\n        'job_id',\n        'status'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
       job_id: {
         type: 'string',
       },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
     },
+    required: ['job_id'],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const { job_id, ...body } = args as any;
-  return client.jobs.manual.retrieve(job_id);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { job_id, jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(await maybeFilter(jq_filter, await client.jobs.manual.retrieve(job_id)));
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/payroll/pay-groups/list-payroll-pay-groups.ts

@@ -1,21 +1,34 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { isJqError, maybeFilter } from '@tryfinch/finch-api-mcp/filtering';
+import { Metadata, asErrorResult, asTextContentResult } from '@tryfinch/finch-api-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Metadata } from '../../';
 import Finch from '@tryfinch/finch-api';
 
 export const metadata: Metadata = {
   resource: 'payroll.pay_groups',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/pay-groups',
+  operationId: 'get-all-pay-groups',
 };
 
 export const tool: Tool = {
   name: 'list_payroll_pay_groups',
-  description: 'Read company pay groups and frequencies',
+  description:
+    "When using this tool, always use the `jq_filter` parameter to reduce the response size and improve performance.\n\nOnly omit if you're sure you don't need the data.\n\nRead company pay groups and frequencies\n\n# Response Schema\n```json\n{\n  type: 'array',\n  items: {\n    $ref: '#/$defs/pay_group_list_response'\n  },\n  $defs: {\n    pay_group_list_response: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'Finch id (uuidv4) for the pay group'\n        },\n        name: {\n          type: 'string',\n          description: 'Name of the pay group'\n        },\n        pay_frequencies: {\n          type: 'array',\n          description: 'List of pay frequencies associated with this pay group',\n          items: {\n            type: 'string',\n            enum: [              'annually',\n              'bi_weekly',\n              'daily',\n              'monthly',\n              'other',\n              'quarterly',\n              'semi_annually',\n              'semi_monthly',\n              'weekly'\n            ]\n          }\n        }\n      },\n      required: [        'id',\n        'name',\n        'pay_frequencies'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
+      entity_ids: {
+        type: 'array',
+        description: "The entity IDs to specify which entities' data to access.",
+        items: {
+          type: 'string',
+        },
+      },
       individual_id: {
         type: 'string',
       },
@@ -25,13 +38,31 @@ export const tool: Tool = {
           type: 'string',
         },
       },
+      jq_filter: {
+        type: 'string',
+        title: 'jq Filter',
+        description:
+          'A jq filter to apply to the response to include certain fields. Consult the output schema in the tool description to see the fields that are available.\n\nFor example: to include only the `name` field in every object of a results array, you can provide ".results[].name".\n\nFor more information, see the [jq documentation](https://jqlang.org/manual/).',
+      },
     },
+    required: [],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.payroll.payGroups.list(body);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  const response = await client.payroll.payGroups.list(body).asResponse();
+  try {
+    return asTextContentResult(await maybeFilter(jq_filter, await response.json()));
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };