@tryfinch/finch-api-mcp 6.31.0 → 7.0.0

package/src/tools/hris/company/pay-statement-item/rules/delete-pay-statement-item-company-hris-rules.ts

@@ -1,32 +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.company.pay_statement_item.rules',
   operation: 'write',
   tags: [],
+  httpMethod: 'delete',
+  httpPath: '/employer/pay-statement-item/rule/{rule_id}',
+  operationId: 'delete-rule',
 };
 
 export const tool: Tool = {
   name: 'delete_pay_statement_item_company_hris_rules',
   description:
-    '**Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon\nDelete a rule for a pay statement item.\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\nDelete a rule for a pay statement item.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/rule_delete_response',\n  $defs: {\n    rule_delete_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        deleted_at: {\n          type: 'string',\n          description: 'The datetime when the rule was deleted.',\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: {
       rule_id: {
         type: 'string',
       },
+      entity_ids: {
+        type: 'array',
+        description: 'The entity IDs to delete the rule for.',
+        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: ['rule_id'],
+  },
+  annotations: {
+    idempotentHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const { rule_id, ...body } = args as any;
-  return client.hris.company.payStatementItem.rules.delete(rule_id);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { rule_id, jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(
+      await maybeFilter(jq_filter, await client.hris.company.payStatementItem.rules.delete(rule_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/rules/list-pay-statement-item-company-hris-rules.ts

@@ -1,27 +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.company.pay_statement_item.rules',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/pay-statement-item/rule',
+  operationId: 'get-rules',
 };
 
 export const tool: Tool = {
   name: 'list_pay_statement_item_company_hris_rules',
   description:
-    '**Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon\nList all rules of a 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\nList all rules of a 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/rule_list_response'\n      }\n    }\n  },\n  required: [    'responses'\n  ],\n  $defs: {\n    rule_list_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: {},
+    properties: {
+      entity_ids: {
+        type: 'array',
+        description: 'The entity IDs to retrieve rules for.',
+        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.company.payStatementItem.rules.list();
+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.rules.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/update-pay-statement-item-company-hris-rules.ts

@@ -1,35 +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.company.pay_statement_item.rules',
   operation: 'write',
   tags: [],
+  httpMethod: 'put',
+  httpPath: '/employer/pay-statement-item/rule/{rule_id}',
+  operationId: 'update-rule',
 };
 
 export const tool: Tool = {
   name: 'update_pay_statement_item_company_hris_rules',
   description:
-    '**Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon\nUpdate a rule for a pay statement item.\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\nUpdate a rule for a pay statement item.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/rule_update_response',\n  $defs: {\n    rule_update_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: {
       rule_id: {
         type: 'string',
       },
+      entity_ids: {
+        type: 'array',
+        description: 'The entity IDs to update the rule for.',
+        items: {
+          type: 'string',
+        },
+      },
       optionalProperty: {
         type: 'object',
+        additionalProperties: true,
+      },
+      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: ['rule_id'],
+  },
+  annotations: {
+    idempotentHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const { rule_id, ...body } = args as any;
-  return client.hris.company.payStatementItem.rules.update(rule_id, body);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { rule_id, jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(
+      await maybeFilter(jq_filter, await client.hris.company.payStatementItem.rules.update(rule_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/retrieve-hris-company.ts

@@ -1,26 +1,58 @@
 // 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',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/company',
+  operationId: 'get-company',
 };
 
 export const tool: Tool = {
   name: 'retrieve_hris_company',
-  description: 'Read basic company 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 basic company data\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/company',\n  $defs: {\n    company: {\n      type: 'object',\n      title: 'GetCompany',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'A stable Finch `id` (UUID v4) for the company.'\n        },\n        accounts: {\n          type: 'array',\n          description: 'An array of bank account objects associated with the payroll/HRIS system.',\n          items: {\n            type: 'object',\n            properties: {\n              account_name: {\n                type: 'string',\n                description: 'The name of the bank associated in the payroll/HRIS system.'\n              },\n              account_number: {\n                type: 'string',\n                description: '10-12 digit number to specify the bank account'\n              },\n              account_type: {\n                type: 'string',\n                description: 'The type of bank account.',\n                enum: [                  'checking',\n                  'savings'\n                ]\n              },\n              institution_name: {\n                type: 'string',\n                description: 'Name of the banking institution.'\n              },\n              routing_number: {\n                type: 'string',\n                description: 'A nine-digit code that\\'s based on the U.S. Bank location where your account was opened.'\n              }\n            },\n            required: [              'account_name',\n              'account_number',\n              'account_type',\n              'institution_name',\n              'routing_number'\n            ]\n          }\n        },\n        departments: {\n          type: 'array',\n          description: 'The array of company departments.',\n          items: {\n            type: 'object',\n            properties: {\n              name: {\n                type: 'string',\n                description: 'The department name.'\n              },\n              parent: {\n                type: 'object',\n                description: 'The parent department, if present.',\n                properties: {\n                  name: {\n                    type: 'string',\n                    description: 'The parent department\\'s name.'\n                  }\n                },\n                required: [                  'name'\n                ]\n              }\n            },\n            required: [              'name',\n              'parent'\n            ]\n          }\n        },\n        ein: {\n          type: 'string',\n          description: 'The employer identification number.'\n        },\n        entity: {\n          type: 'object',\n          description: 'The entity type object.',\n          properties: {\n            subtype: {\n              type: 'string',\n              description: 'The tax payer subtype of the company.',\n              enum: [                's_corporation',\n                'c_corporation',\n                'b_corporation'\n              ]\n            },\n            type: {\n              type: 'string',\n              description: 'The tax payer type of the company.',\n              enum: [                'llc',\n                'lp',\n                'corporation',\n                'sole_proprietor',\n                'non_profit',\n                'partnership',\n                'cooperative'\n              ]\n            }\n          },\n          required: [            'subtype',\n            'type'\n          ]\n        },\n        legal_name: {\n          type: 'string',\n          description: 'The legal name of the company.'\n        },\n        locations: {\n          type: 'array',\n          items: {\n            $ref: '#/$defs/location'\n          }\n        },\n        primary_email: {\n          type: 'string',\n          description: 'The email of the main administrator on the account.'\n        },\n        primary_phone_number: {\n          type: 'string',\n          description: 'The phone number of the main administrator on the account. Format: E.164, with extension where applicable, e.g. `+NNNNNNNNNNN xExtension`'\n        }\n      },\n      required: [        'id',\n        'accounts',\n        'departments',\n        'ein',\n        'entity',\n        'legal_name',\n        'locations',\n        'primary_email',\n        'primary_phone_number'\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: {},
+    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.company.retrieve();
+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.retrieve(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/directory/list-hris-directory.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.directory',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/directory',
+  operationId: 'get-directory',
 };
 
 export const tool: Tool = {
   name: 'list_hris_directory',
-  description: 'Read company directory and organization structure',
+  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 directory and organization structure\n\n# Response Schema\n```json\n{\n  type: 'object',\n  properties: {\n    individuals: {\n      type: 'array',\n      description: 'The array of employees.',\n      items: {\n        $ref: '#/$defs/individual_in_directory'\n      }\n    },\n    paging: {\n      $ref: '#/$defs/paging'\n    }\n  },\n  required: [    'individuals',\n    'paging'\n  ],\n  $defs: {\n    individual_in_directory: {\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        department: {\n          type: 'object',\n          description: 'The department object.',\n          properties: {\n            name: {\n              type: 'string',\n              description: 'The name of the department.'\n            }\n          }\n        },\n        first_name: {\n          type: 'string',\n          description: 'The legal first name of the individual.'\n        },\n        is_active: {\n          type: 'boolean',\n          description: '`true` if the individual is an active employee or contractor at the company.'\n        },\n        last_name: {\n          type: 'string',\n          description: 'The legal last name of the individual.'\n        },\n        manager: {\n          type: 'object',\n          description: 'The manager object.',\n          properties: {\n            id: {\n              type: 'string',\n              description: 'A stable Finch `id` (UUID v4) for an individual in the company.'\n            }\n          },\n          required: [            'id'\n          ]\n        },\n        middle_name: {\n          type: 'string',\n          description: 'The legal middle name of the individual.'\n        }\n      },\n      required: [        'id',\n        'department',\n        'first_name',\n        'is_active',\n        'last_name',\n        'manager',\n        'middle_name'\n      ]\n    },\n    paging: {\n      type: 'object',\n      title: 'Paging',\n      properties: {\n        offset: {\n          type: 'integer',\n          description: 'The current start index of the returned list of elements'\n        },\n        count: {\n          type: 'integer',\n          description: 'The total number of elements for the entire query (not just the given page)'\n        }\n      },\n      required: [        'offset'\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',
+        },
+      },
       limit: {
         type: 'integer',
         description: 'Number of employees to return (defaults to all)',
@@ -24,13 +37,31 @@ 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.hris.directory.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.directory.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/documents/list-hris-documents.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.documents',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/documents',
+  operationId: 'list-documents',
 };
 
 export const tool: Tool = {
   name: 'list_hris_documents',
   description:
-    '**Beta:** This endpoint is in beta and may change.\nRetrieve a list of company-wide documents.\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 is in beta and may change.\nRetrieve a list of company-wide documents.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/document_list_response',\n  $defs: {\n    document_list_response: {\n      type: 'object',\n      properties: {\n        documents: {\n          type: 'array',\n          items: {\n            $ref: '#/$defs/document_response'\n          }\n        },\n        paging: {\n          $ref: '#/$defs/paging'\n        }\n      },\n      required: [        'documents',\n        'paging'\n      ]\n    },\n    document_response: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'A stable Finch id for the document.'\n        },\n        individual_id: {\n          type: 'string',\n          description: 'The ID of the individual associated with the document. This will be null for employer-level documents.'\n        },\n        type: {\n          type: 'string',\n          description: 'The type of document.',\n          enum: [            'w4_2020',\n            'w4_2005'\n          ]\n        },\n        url: {\n          type: 'string',\n          description: 'A URL to access the document. Format: `https://api.tryfinch.com/employer/documents/:document_id`.'\n        },\n        year: {\n          type: 'number',\n          description: 'The year the document applies to, if available.'\n        }\n      },\n      required: [        'id',\n        'individual_id',\n        'type',\n        'url',\n        'year'\n      ]\n    },\n    paging: {\n      type: 'object',\n      title: 'Paging',\n      properties: {\n        offset: {\n          type: 'integer',\n          description: 'The current start index of the returned list of elements'\n        },\n        count: {\n          type: 'integer',\n          description: 'The total number of elements for the entire query (not just the given page)'\n        }\n      },\n      required: [        'offset'\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_ids: {
         type: 'array',
         description:
@@ -41,13 +53,30 @@ export const tool: Tool = {
           enum: ['w4_2020', 'w4_2005'],
         },
       },
+      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.documents.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.hris.documents.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/hris/documents/retreive-hris-documents.ts

@@ -1,32 +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.documents',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/documents/{document_id}',
+  operationId: 'get-document',
 };
 
 export const tool: Tool = {
   name: 'retreive_hris_documents',
   description:
-    '**Beta:** This endpoint is in beta and may change.\nRetrieve details of a specific document by its ID.\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 is in beta and may change.\nRetrieve details of a specific document by its ID.\n\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/document_retreive_response',\n  $defs: {\n    document_retreive_response: {\n      anyOf: [        {\n          $ref: '#/$defs/w42020'\n        },\n        {\n          $ref: '#/$defs/w42005'\n        }\n      ],\n      description: 'A 2020 version of the W-4 tax form containing information on an individual\\'s filing status, dependents, and withholding details.'\n    },\n    w42020: {\n      type: 'object',\n      description: 'A 2020 version of the W-4 tax form containing information on an individual\\'s filing status, dependents, and withholding details.',\n      properties: {\n        data: {\n          type: 'object',\n          description: 'Detailed information specific to the 2020 W4 form.',\n          properties: {\n            amount_for_other_dependents: {\n              type: 'integer',\n              description: 'Amount claimed for dependents other than qualifying children under 17 (in cents).'\n            },\n            amount_for_qualifying_children_under_17: {\n              type: 'integer',\n              description: 'Amount claimed for dependents under 17 years old (in cents).'\n            },\n            deductions: {\n              type: 'integer',\n              description: 'Deductible expenses (in cents).'\n            },\n            extra_withholding: {\n              type: 'integer',\n              description: 'Additional withholding amount (in cents).'\n            },\n            filing_status: {\n              type: 'string',\n              description: 'The individual\\'s filing status for tax purposes.',\n              enum: [                'head_of_household',\n                'married_filing_jointly_or_qualifying_surviving_spouse',\n                'single_or_married_filing_separately'\n              ]\n            },\n            individual_id: {\n              type: 'string',\n              description: 'The unique identifier for the individual associated with this document.'\n            },\n            other_income: {\n              type: 'integer',\n              description: 'Additional income from sources outside of primary employment (in cents).'\n            },\n            total_claim_dependent_and_other_credits: {\n              type: 'integer',\n              description: 'Total amount claimed for dependents and other credits (in cents).'\n            }\n          },\n          required: [            'amount_for_other_dependents',\n            'amount_for_qualifying_children_under_17',\n            'deductions',\n            'extra_withholding',\n            'filing_status',\n            'individual_id',\n            'other_income',\n            'total_claim_dependent_and_other_credits'\n          ]\n        },\n        type: {\n          type: 'string',\n          description: 'Specifies the form type, indicating that this document is a 2020 W4 form.',\n          enum: [            'w4_2020'\n          ]\n        },\n        year: {\n          type: 'number',\n          description: 'The tax year this W4 document applies to.'\n        }\n      },\n      required: [        'data',\n        'type',\n        'year'\n      ]\n    },\n    w42005: {\n      type: 'object',\n      description: 'A 2005 version of the W-4 tax form containing information on an individual\\'s filing status, dependents, and withholding details.',\n      properties: {\n        data: {\n          type: 'object',\n          description: 'Detailed information specific to the 2005 W4 form.',\n          properties: {\n            additional_withholding: {\n              type: 'integer',\n              description: 'Additional withholding amount (in cents).'\n            },\n            exemption: {\n              type: 'string',\n              description: 'Indicates exemption status from federal tax withholding.',\n              enum: [                'exempt',\n                'non_exempt'\n              ]\n            },\n            filing_status: {\n              type: 'string',\n              description: 'The individual\\'s filing status for tax purposes.',\n              enum: [                'married',\n                'married_but_withhold_at_higher_single_rate',\n                'single'\n              ]\n            },\n            individual_id: {\n              type: 'string',\n              description: 'The unique identifier for the individual associated with this 2005 W4 form.'\n            },\n            total_number_of_allowances: {\n              type: 'integer',\n              description: 'Total number of allowances claimed (in cents).'\n            }\n          },\n          required: [            'additional_withholding',\n            'exemption',\n            'filing_status',\n            'individual_id',\n            'total_number_of_allowances'\n          ]\n        },\n        type: {\n          type: 'string',\n          description: 'Specifies the form type, indicating that this document is a 2005 W4 form.',\n          enum: [            'w4_2005'\n          ]\n        },\n        year: {\n          type: 'number',\n          description: 'The tax year this W4 document applies to.'\n        }\n      },\n      required: [        'data',\n        'type',\n        'year'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
       document_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: ['document_id'],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const { document_id, ...body } = args as any;
-  return client.hris.documents.retreive(document_id);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { document_id, jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(
+      await maybeFilter(jq_filter, await client.hris.documents.retreive(document_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/employments/retrieve-many-hris-employments.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.employments',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/employer/employment',
+  operationId: 'get-employment',
 };
 
 export const tool: Tool = {
@@ -31,13 +35,30 @@ export const tool: Tool = {
           required: ['individual_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.employments.retrieveMany(body);
+  const response = await client.hris.employments.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 };