@tryfinch/finch-api-mcp 6.30.0 → 7.0.0

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

@@ -1,36 +1,67 @@
 // 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.benefits.individuals',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/benefits/{benefit_id}/individuals',
+  operationId: 'get-individual-benefits',
 };
 
 export const tool: Tool = {
   name: 'retrieve_many_benefits_benefits_hris_individuals',
-  description: 'Get enrollment information for the given individuals.',
+  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 enrollment information for the given individuals.\n\n# Response Schema\n```json\n{\n  type: 'array',\n  title: 'IndividualBenefits',\n  items: {\n    $ref: '#/$defs/individual_benefit'\n  },\n  $defs: {\n    individual_benefit: {\n      type: 'object',\n      properties: {\n        body: {\n          anyOf: [            {\n              type: 'object',\n              properties: {\n                annual_maximum: {\n                  type: 'integer',\n                  description: 'If the benefit supports annual maximum, the amount in cents for this individual.'\n                },\n                catch_up: {\n                  type: 'boolean',\n                  description: 'If the benefit supports catch up (401k, 403b, etc.), whether catch up is enabled for this individual.'\n                },\n                company_contribution: {\n                  anyOf: [                    {\n                      type: 'object',\n                      properties: {\n                        amount: {\n                          type: 'integer',\n                          description: 'Contribution amount in cents (for type=fixed) or basis points (for type=percent, where 100 = 1%). Not used for type=tiered.'\n                        },\n                        type: {\n                          type: 'string',\n                          description: 'Contribution type. Supported values: \"fixed\" (amount in cents), \"percent\" (amount in basis points), or \"tiered\" (multi-tier matching).',\n                          enum: [                            'fixed'\n                          ]\n                        }\n                      },\n                      required: [                        'amount',\n                        'type'\n                      ]\n                    },\n                    {\n                      type: 'object',\n                      properties: {\n                        amount: {\n                          type: 'integer',\n                          description: 'Contribution amount in cents (for type=fixed) or basis points (for type=percent, where 100 = 1%). Not used for type=tiered.'\n                        },\n                        type: {\n                          type: 'string',\n                          description: 'Contribution type. Supported values: \"fixed\" (amount in cents), \"percent\" (amount in basis points), or \"tiered\" (multi-tier matching).',\n                          enum: [                            'percent'\n                          ]\n                        }\n                      },\n                      required: [                        'amount',\n                        'type'\n                      ]\n                    },\n                    {\n                      type: 'object',\n                      properties: {\n                        tiers: {\n                          type: 'array',\n                          description: 'Array of tier objects defining employer match tiers based on employee contribution thresholds. Required when type=tiered.',\n                          items: {\n                            type: 'object',\n                            properties: {\n                              match: {\n                                type: 'integer'\n                              },\n                              threshold: {\n                                type: 'integer'\n                              }\n                            },\n                            required: [                              'match',\n                              'threshold'\n                            ]\n                          }\n                        },\n                        type: {\n                          type: 'string',\n                          description: 'Contribution type. Supported values: \"fixed\" (amount in cents), \"percent\" (amount in basis points), or \"tiered\" (multi-tier matching).',\n                          enum: [                            'tiered'\n                          ]\n                        }\n                      },\n                      required: [                        'tiers',\n                        'type'\n                      ]\n                    }\n                  ],\n                  title: 'CompanyContribution',\n                  description: 'Company contribution configuration. Supports fixed amounts (in cents), percentage-based contributions (in basis points where 100 = 1%), or tiered matching structures.'\n                },\n                employee_deduction: {\n                  anyOf: [                    {\n                      type: 'object',\n                      properties: {\n                        amount: {\n                          type: 'integer',\n                          description: 'Contribution amount in cents (for type=fixed) or basis points (for type=percent, where 100 = 1%).'\n                        },\n                        type: {\n                          type: 'string',\n                          description: 'Contribution type. Supported values: \"fixed\" (amount in cents) or \"percent\" (amount in basis points).',\n                          enum: [                            'fixed'\n                          ]\n                        }\n                      },\n                      required: [                        'amount',\n                        'type'\n                      ]\n                    },\n                    {\n                      type: 'object',\n                      properties: {\n                        amount: {\n                          type: 'integer',\n                          description: 'Contribution amount in cents (for type=fixed) or basis points (for type=percent, where 100 = 1%).'\n                        },\n                        type: {\n                          type: 'string',\n                          description: 'Contribution type. Supported values: \"fixed\" (amount in cents) or \"percent\" (amount in basis points).',\n                          enum: [                            'percent'\n                          ]\n                        }\n                      },\n                      required: [                        'amount',\n                        'type'\n                      ]\n                    }\n                  ],\n                  title: 'EmployeeDeductionContribution',\n                  description: 'Employee deduction configuration. Supports both fixed amounts (in cents) and percentage-based contributions (in basis points where 100 = 1%).'\n                },\n                hsa_contribution_limit: {\n                  type: 'string',\n                  description: 'Type for HSA contribution limit if the benefit is a HSA.',\n                  enum: [                    'individual',\n                    'family'\n                  ]\n                }\n              },\n              required: [                'annual_maximum',\n                'catch_up',\n                'company_contribution',\n                'employee_deduction'\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        code: {\n          type: 'integer'\n        },\n        individual_id: {\n          type: 'string'\n        }\n      },\n      required: [        'body',\n        'code',\n        'individual_id'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
       benefit_id: {
         type: 'string',
       },
+      entity_ids: {
+        type: 'array',
+        description: "The entity IDs to specify which entities' data to access.",
+        items: {
+          type: 'string',
+        },
+      },
       individual_ids: {
         type: 'string',
         description:
           'comma-delimited list of stable Finch uuids for each individual. If empty, defaults to all individuals',
       },
+      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: ['benefit_id'],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const { benefit_id, ...body } = args as any;
-  return client.hris.benefits.individuals.retrieveManyBenefits(benefit_id, body);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { benefit_id, jq_filter, ...body } = args as any;
+  const response = await client.hris.benefits.individuals.retrieveManyBenefits(benefit_id, 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/benefits/individuals/unenroll-many-benefits-hris-individuals.ts

@@ -1,24 +1,37 @@
 // 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.benefits.individuals',
   operation: 'write',
   tags: [],
+  httpMethod: 'delete',
+  httpPath: '/employer/benefits/{benefit_id}/individuals',
+  operationId: 'delete-individual-benefits',
 };
 
 export const tool: Tool = {
   name: 'unenroll_many_benefits_hris_individuals',
-  description: 'Unenroll individuals from a deduction or contribution',
+  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\nUnenroll individuals from a deduction or contribution\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/unenrolled_individual_benefit_response',\n  $defs: {\n    unenrolled_individual_benefit_response: {\n      type: 'object',\n      properties: {\n        job_id: {\n          type: 'string'\n        }\n      },\n      required: [        'job_id'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
       benefit_id: {
         type: 'string',
       },
+      entity_ids: {
+        type: 'array',
+        description: "The entity IDs to specify which entities' data to access.",
+        items: {
+          type: 'string',
+        },
+      },
       individual_ids: {
         type: 'array',
         description: 'Array of individual_ids to unenroll.',
@@ -26,13 +39,32 @@ 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: ['benefit_id'],
+  },
+  annotations: {
+    idempotentHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const { benefit_id, ...body } = args as any;
-  return client.hris.benefits.individuals.unenrollMany(benefit_id, body);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { benefit_id, jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(
+      await maybeFilter(jq_filter, await client.hris.benefits.individuals.unenrollMany(benefit_id, body)),
+    );
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

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

@@ -1,26 +1,59 @@
 // 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.benefits',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/benefits',
+  operationId: 'get-company-benefits',
 };
 
 export const tool: Tool = {
   name: 'list_hris_benefits',
-  description: 'List all company-wide deductions and contributions.',
+  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\nList all company-wide deductions and contributions.\n\n# Response Schema\n```json\n{\n  type: 'array',\n  description: 'Array of company benefits.',\n  items: {\n    $ref: '#/$defs/company_benefit'\n  },\n  $defs: {\n    company_benefit: {\n      type: 'object',\n      title: 'CompanyBenefit',\n      properties: {\n        benefit_id: {\n          type: 'string',\n          description: 'The id of the benefit.'\n        },\n        description: {\n          type: 'string'\n        },\n        frequency: {\n          $ref: '#/$defs/benefit_frequency'\n        },\n        type: {\n          $ref: '#/$defs/benefit_type'\n        },\n        company_contribution: {\n          type: 'object',\n          title: 'BenefitCompanyMatchContribution',\n          description: 'The company match for this benefit.',\n          properties: {\n            tiers: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  match: {\n                    type: 'integer'\n                  },\n                  threshold: {\n                    type: 'integer'\n                  }\n                },\n                required: [                  'match',\n                  'threshold'\n                ]\n              }\n            },\n            type: {\n              type: 'string',\n              enum: [                'match'\n              ]\n            }\n          },\n          required: [            'tiers',\n            'type'\n          ]\n        }\n      },\n      required: [        'benefit_id',\n        'description',\n        'frequency',\n        'type'\n      ]\n    },\n    benefit_frequency: {\n      type: 'string',\n      title: 'BenefitFrequency',\n      description: 'The frequency of the benefit deduction/contribution.',\n      enum: [        'every_paycheck',\n        'monthly',\n        'one_time'\n      ]\n    },\n    benefit_type: {\n      type: 'string',\n      title: 'BenefitType',\n      description: 'Type of benefit.',\n      enum: [        '457',\n        '401k',\n        '401k_roth',\n        '401k_loan',\n        '403b',\n        '403b_roth',\n        '457_roth',\n        'commuter',\n        'custom_post_tax',\n        'custom_pre_tax',\n        'fsa_dependent_care',\n        'fsa_medical',\n        'hsa_post',\n        'hsa_pre',\n        's125_dental',\n        's125_medical',\n        's125_vision',\n        'simple',\n        'simple_ira'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
-    properties: {},
+    properties: {
+      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: [],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  return client.hris.benefits.list();
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  const response = await client.hris.benefits.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/hris/benefits/list-supported-benefits-hris-benefits.ts

@@ -1,26 +1,59 @@
 // 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.benefits',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/benefits/meta',
+  operationId: 'get-company-benefits-meta',
 };
 
 export const tool: Tool = {
   name: 'list_supported_benefits_hris_benefits',
-  description: 'Get deductions metadata',
+  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 deductions metadata\n\n# Response Schema\n```json\n{\n  type: 'array',\n  items: {\n    $ref: '#/$defs/supported_benefit'\n  },\n  $defs: {\n    supported_benefit: {\n      type: 'object',\n      title: 'BenefitFeature',\n      properties: {\n        annual_maximum: {\n          type: 'boolean',\n          description: 'Whether the provider supports an annual maximum for this benefit.'\n        },\n        company_contribution: {\n          type: 'array',\n          description: 'Supported contribution types. An empty array indicates contributions are not supported.',\n          items: {\n            type: 'string',\n            enum: [              'fixed',\n              'percent',\n              'tiered'\n            ]\n          }\n        },\n        description: {\n          type: 'string'\n        },\n        employee_deduction: {\n          type: 'array',\n          description: 'Supported deduction types. An empty array indicates deductions are not supported.',\n          items: {\n            type: 'string',\n            enum: [              'fixed',\n              'percent'\n            ]\n          }\n        },\n        frequencies: {\n          type: 'array',\n          description: 'The list of frequencies supported by the provider for this benefit',\n          items: {\n            $ref: '#/$defs/benefit_frequency'\n          }\n        },\n        catch_up: {\n          type: 'boolean',\n          description: 'Whether the provider supports catch up for this benefit. This field will only be true for retirement benefits.'\n        },\n        hsa_contribution_limit: {\n          type: 'array',\n          description: 'Whether the provider supports HSA contribution limits. Empty if this feature is not supported for the benefit. This array only has values for HSA benefits.',\n          items: {\n            type: 'string',\n            enum: [              'family',\n              'individual'\n            ]\n          }\n        }\n      },\n      required: [        'annual_maximum',\n        'company_contribution',\n        'description',\n        'employee_deduction',\n        'frequencies'\n      ]\n    },\n    benefit_frequency: {\n      type: 'string',\n      title: 'BenefitFrequency',\n      description: 'The frequency of the benefit deduction/contribution.',\n      enum: [        'every_paycheck',\n        'monthly',\n        'one_time'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
-    properties: {},
+    properties: {
+      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: [],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  return client.hris.benefits.listSupportedBenefits();
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { jq_filter, ...body } = args as any;
+  const response = await client.hris.benefits.listSupportedBenefits(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/benefits/retrieve-hris-benefits.ts

@@ -1,31 +1,63 @@
 // 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.benefits',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/benefits/{benefit_id}',
+  operationId: 'get-company-benefit',
 };
 
 export const tool: Tool = {
   name: 'retrieve_hris_benefits',
-  description: 'Lists deductions and contributions information for a given item',
+  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\nLists deductions and contributions information for a given item\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/company_benefit',\n  $defs: {\n    company_benefit: {\n      type: 'object',\n      title: 'CompanyBenefit',\n      properties: {\n        benefit_id: {\n          type: 'string',\n          description: 'The id of the benefit.'\n        },\n        description: {\n          type: 'string'\n        },\n        frequency: {\n          $ref: '#/$defs/benefit_frequency'\n        },\n        type: {\n          $ref: '#/$defs/benefit_type'\n        },\n        company_contribution: {\n          type: 'object',\n          title: 'BenefitCompanyMatchContribution',\n          description: 'The company match for this benefit.',\n          properties: {\n            tiers: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  match: {\n                    type: 'integer'\n                  },\n                  threshold: {\n                    type: 'integer'\n                  }\n                },\n                required: [                  'match',\n                  'threshold'\n                ]\n              }\n            },\n            type: {\n              type: 'string',\n              enum: [                'match'\n              ]\n            }\n          },\n          required: [            'tiers',\n            'type'\n          ]\n        }\n      },\n      required: [        'benefit_id',\n        'description',\n        'frequency',\n        'type'\n      ]\n    },\n    benefit_frequency: {\n      type: 'string',\n      title: 'BenefitFrequency',\n      description: 'The frequency of the benefit deduction/contribution.',\n      enum: [        'every_paycheck',\n        'monthly',\n        'one_time'\n      ]\n    },\n    benefit_type: {\n      type: 'string',\n      title: 'BenefitType',\n      description: 'Type of benefit.',\n      enum: [        '457',\n        '401k',\n        '401k_roth',\n        '401k_loan',\n        '403b',\n        '403b_roth',\n        '457_roth',\n        'commuter',\n        'custom_post_tax',\n        'custom_pre_tax',\n        'fsa_dependent_care',\n        'fsa_medical',\n        'hsa_post',\n        'hsa_pre',\n        's125_dental',\n        's125_medical',\n        's125_vision',\n        'simple',\n        'simple_ira'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
       benefit_id: {
         type: 'string',
       },
+      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: ['benefit_id'],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const { benefit_id, ...body } = args as any;
-  return client.hris.benefits.retrieve(benefit_id);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { benefit_id, jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(
+      await maybeFilter(jq_filter, await client.hris.benefits.retrieve(benefit_id, body)),
+    );
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/hris/benefits/update-hris-benefits.ts

@@ -1,35 +1,65 @@
 // 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.benefits',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/employer/benefits/{benefit_id}',
+  operationId: 'update-company-benefits',
 };
 
 export const tool: Tool = {
   name: 'update_hris_benefits',
-  description: 'Updates an existing company-wide deduction or contribution',
+  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\nUpdates an existing company-wide deduction or contribution\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/update_company_benefit_response',\n  $defs: {\n    update_company_benefit_response: {\n      type: 'object',\n      properties: {\n        benefit_id: {\n          type: 'string',\n          description: 'The id of the benefit.'\n        },\n        job_id: {\n          type: 'string'\n        }\n      },\n      required: [        'benefit_id',\n        'job_id'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
       benefit_id: {
         type: 'string',
       },
+      entity_ids: {
+        type: 'array',
+        description: "The entity IDs to specify which entities' data to access.",
+        items: {
+          type: 'string',
+        },
+      },
       description: {
         type: 'string',
         description: 'Updated name or description.',
       },
+      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: ['benefit_id'],
   },
+  annotations: {},
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const { benefit_id, ...body } = args as any;
-  return client.hris.benefits.update(benefit_id, body);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { benefit_id, jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(
+      await maybeFilter(jq_filter, await client.hris.benefits.update(benefit_id, body)),
+    );
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/hris/company/pay-statement-item/list-company-hris-pay-statement-item.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: 'hris.company.pay_statement_item',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/pay-statement-item',
+  operationId: 'get-pay-statement-item',
 };
 
 export const tool: Tool = {
   name: 'list_company_hris_pay_statement_item',
   description:
-    "**Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon\n Retrieve a list of detailed pay statement items for the access token's connection account.\n",
+    "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\n**Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon\n Retrieve a list of detailed pay statement items for the access token's connection account.\n\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    responses: {\n      type: 'array',\n      items: {\n        $ref: '#/$defs/pay_statement_item_list_response'\n      }\n    }\n  },\n  required: [    'responses'\n  ],\n  $defs: {\n    pay_statement_item_list_response: {\n      type: 'object',\n      properties: {\n        attributes: {\n          type: 'object',\n          description: 'The attributes of the pay statement item.',\n          properties: {\n            metadata: {\n              type: 'object',\n              description: 'The metadata of the pay statement item derived by the rules engine if available. Each attribute will be a key-value pair defined by a rule.',\n              additionalProperties: true\n            },\n            employer: {\n              type: 'boolean',\n              description: '`true` if the amount is paid by the employers. This field is only available for taxes.'\n            },\n            pre_tax: {\n              type: 'boolean',\n              description: '`true` if the pay statement item is pre-tax. This field is only available for employee deductions.'\n            },\n            type: {\n              type: 'string',\n              description: 'The type of the pay statement item.'\n            }\n          },\n          required: [            'metadata'\n          ]\n        },\n        category: {\n          type: 'string',\n          description: 'The category of the pay statement item.',\n          enum: [            'earnings',\n            'taxes',\n            'employee_deductions',\n            'employer_contributions'\n          ]\n        },\n        name: {\n          type: 'string',\n          description: 'The name of the pay statement item.'\n        }\n      },\n      required: [        'attributes',\n        'category',\n        'name'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -32,6 +37,13 @@ export const tool: Tool = {
           'The end date to retrieve pay statement items by via their last seen pay date 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',
+        },
+      },
       name: {
         type: 'string',
         description: 'Case-insensitive partial match search by pay statement item name.',
@@ -46,13 +58,31 @@ export const tool: Tool = {
         type: 'string',
         description: 'String search by pay statement item type.',
       },
+      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.hris.company.payStatementItem.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.company.payStatementItem.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/hris/company/pay-statement-item/rules/create-pay-statement-item-company-hris-rules.ts

@@ -1,22 +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.company.pay_statement_item.rules',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/employer/pay-statement-item/rule',
+  operationId: 'create-rule',
 };
 
 export const tool: Tool = {
   name: 'create_pay_statement_item_company_hris_rules',
   description:
-    '**Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon\nCustom rules can be created to associate specific attributes to pay statement items depending on the use case. For example, pay statement items that meet certain conditions can be labeled as a pre-tax 401k. This metadata can be retrieved where pay statement item information is available.\n',
+    "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\n**Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon\nCustom rules can be created to associate specific attributes to pay statement items depending on the use case. For example, pay statement items that meet certain conditions can be labeled as a pre-tax 401k. This metadata can be retrieved where pay statement item information is available.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/rule_create_response',\n  $defs: {\n    rule_create_response: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'Finch id (uuidv4) for the rule.'\n        },\n        attributes: {\n          type: 'object',\n          description: 'Specifies the fields to be applied when the condition is met.',\n          properties: {\n            metadata: {\n              type: 'object',\n              description: 'The metadata to be attached in the entity. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).',\n              additionalProperties: true\n            }\n          }\n        },\n        conditions: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              field: {\n                type: 'string',\n                description: 'The field to be checked in the rule.'\n              },\n              operator: {\n                type: 'string',\n                description: 'The operator to be used in the rule.',\n                enum: [                  'equals'\n                ]\n              },\n              value: {\n                type: 'string',\n                description: 'The value of the field to be checked in the rule.'\n              }\n            }\n          }\n        },\n        created_at: {\n          type: 'string',\n          description: 'The datetime when the rule was created.',\n          format: 'date-time'\n        },\n        effective_end_date: {\n          type: 'string',\n          title: 'Date',\n          description: 'Specifies when the rules should stop applying rules based on the date.'\n        },\n        effective_start_date: {\n          type: 'string',\n          title: 'Date',\n          description: 'Specifies when the rule should begin applying based on the date.'\n        },\n        entity_type: {\n          type: 'string',\n          description: 'The entity type to which the rule is applied.',\n          enum: [            'pay_statement_item'\n          ]\n        },\n        priority: {\n          type: 'integer',\n          description: 'The priority of the rule.'\n        },\n        updated_at: {\n          type: 'string',\n          description: 'The datetime when the rule was last updated.',\n          format: 'date-time'\n        }\n      }\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
+      entity_ids: {
+        type: 'array',
+        description: 'The entity IDs to create the rule for.',
+        items: {
+          type: 'string',
+        },
+      },
       attributes: {
         type: 'object',
         description: 'Specifies the fields to be applied when the condition is met.',
@@ -25,9 +37,9 @@ export const tool: Tool = {
             type: 'object',
             description:
               'The metadata to be attached in the entity. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).',
+            additionalProperties: true,
           },
         },
-        required: [],
       },
       conditions: {
         type: 'array',
@@ -48,7 +60,6 @@ export const tool: Tool = {
               description: 'The value of the field to be checked in the rule.',
             },
           },
-          required: [],
         },
       },
       effective_end_date: {
@@ -66,13 +77,30 @@ export const tool: Tool = {
         description: 'The entity type to which the rule is applied.',
         enum: ['pay_statement_item'],
       },
+      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.company.payStatementItem.rules.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.hris.company.payStatementItem.rules.create(body)),
+    );
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };