@tryfinch/finch-api-mcp 6.31.0 → 7.0.0

package/src/tools/payroll/pay-groups/retrieve-payroll-pay-groups.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: 'payroll.pay_groups',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/employer/pay-groups/{pay_group_id}',
+  operationId: 'get-pay-group',
 };
 
 export const tool: Tool = {
   name: 'retrieve_payroll_pay_groups',
-  description: 'Read information from a single pay group',
+  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 information from a single pay group\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/pay_group_retrieve_response',\n  $defs: {\n    pay_group_retrieve_response: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'Finch id (uuidv4) for the pay group'\n        },\n        individual_ids: {\n          type: 'array',\n          items: {\n            type: 'string',\n            description: 'Finch id (uuidv4) for an individual assigned to this pay group'\n          }\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        'individual_ids',\n        'name',\n        'pay_frequencies'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
       pay_group_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: ['pay_group_id'],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const { pay_group_id, ...body } = args as any;
-  return client.payroll.payGroups.retrieve(pay_group_id);
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { pay_group_id, jq_filter, ...body } = args as any;
+  try {
+    return asTextContentResult(
+      await maybeFilter(jq_filter, await client.payroll.payGroups.retrieve(pay_group_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/providers/list-providers.ts

@@ -1,26 +1,52 @@
 // 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: 'providers',
   operation: 'read',
   tags: [],
+  httpMethod: 'get',
+  httpPath: '/providers',
+  operationId: 'get-providers',
 };
 
 export const tool: Tool = {
   name: 'list_providers',
-  description: 'Return details on all available payroll and HR systems.',
+  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\nReturn details on all available payroll and HR systems.\n\n# Response Schema\n```json\n{\n  type: 'array',\n  items: {\n    $ref: '#/$defs/provider_list_response'\n  },\n  $defs: {\n    provider_list_response: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'The id of the payroll provider used in Connect.'\n        },\n        display_name: {\n          type: 'string',\n          description: 'The display name of the payroll provider.'\n        },\n        products: {\n          type: 'array',\n          description: 'The list of Finch products supported on this payroll provider.',\n          items: {\n            type: 'string'\n          }\n        },\n        authentication_methods: {\n          type: 'array',\n          description: 'The authentication methods supported by the provider.',\n          items: {\n            type: 'object',\n            properties: {\n              type: {\n                type: 'string',\n                description: 'The type of authentication method',\n                enum: [                  'assisted',\n                  'credential',\n                  'api_token',\n                  'api_credential',\n                  'oauth',\n                  'api'\n                ]\n              },\n              benefits_support: {\n                type: 'object',\n                description: 'The supported benefit types and their configurations',\n                additionalProperties: true\n              },\n              supported_fields: {\n                type: 'object',\n                description: 'The supported fields for each Finch product',\n                additionalProperties: true\n              }\n            },\n            required: [              'type'\n            ]\n          }\n        },\n        beta: {\n          type: 'boolean',\n          description: '`true` if the integration is in a beta state, `false` otherwise'\n        },\n        icon: {\n          type: 'string',\n          description: 'The url to the official icon of the payroll provider.'\n        },\n        logo: {\n          type: 'string',\n          description: 'The url to the official logo of the payroll provider.'\n        },\n        manual: {\n          type: 'boolean',\n          description: '[DEPRECATED] Whether the Finch integration with this provider uses the Assisted Connect Flow by default. This field is now deprecated. Please check for a `type` of `assisted` in the `authentication_methods` field instead.'\n        },\n        mfa_required: {\n          type: 'boolean',\n          description: 'whether MFA is required for the provider.'\n        },\n        primary_color: {\n          type: 'string',\n          description: 'The hex code for the primary color of the payroll provider.'\n        }\n      },\n      required: [        'id',\n        'display_name',\n        'products'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
-    properties: {},
+    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/).',
+      },
+    },
+    required: [],
+  },
+  annotations: {
+    readOnlyHint: true,
   },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  return client.providers.list();
+export const handler = async (client: Finch, args: Record<string, unknown> | undefined) => {
+  const { jq_filter } = args as any;
+  const response = await client.providers.list().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/request-forwarding/forward-request-forwarding.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: 'request_forwarding',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/forward',
+  operationId: 'post-forward',
 };
 
 export const tool: Tool = {
   name: 'forward_request_forwarding',
   description:
-    'The Forward API allows you to make direct requests to an employment system. If Finch’s unified API\ndoesn’t have a data model that cleanly fits your needs, then Forward allows you to push or pull\ndata models directly against an integration’s API.',
+    "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\nThe Forward API allows you to make direct requests to an employment system. If Finch's unified API\ndoesn't have a data model that cleanly fits your needs, then Forward allows you to push or pull\ndata models directly against an integration's API.\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/request_forwarding_forward_response',\n  $defs: {\n    request_forwarding_forward_response: {\n      type: 'object',\n      properties: {\n        request: {\n          type: 'object',\n          description: 'An object containing details of your original forwarded request, for your ease of reference.',\n          properties: {\n            method: {\n              type: 'string',\n              description: 'The HTTP method that was specified for the forwarded request. Valid values include: `GET` , `POST` , `PUT` , `DELETE` , and `PATCH`.'\n            },\n            route: {\n              type: 'string',\n              description: 'The URL route path that was specified for the forwarded request.'\n            },\n            data: {\n              anyOf: [                {\n                  type: 'string'\n                },\n                {\n                  type: 'object',\n                  additionalProperties: true\n                }\n              ],\n              description: 'The body that was specified for the forwarded request.'\n            },\n            headers: {\n              type: 'object',\n              description: 'The HTTP headers that were specified for the forwarded request.',\n              additionalProperties: true\n            },\n            params: {\n              type: 'object',\n              description: 'The query parameters that were specified for the forwarded request.',\n              additionalProperties: true\n            }\n          },\n          required: [            'method',\n            'route'\n          ]\n        },\n        statusCode: {\n          type: 'integer',\n          description: 'The HTTP status code of the forwarded request\\'s response, exactly received from the underlying integration\\'s API. This value will be returned as an integer.'\n        },\n        data: {\n          type: 'string',\n          description: 'A string representation of the HTTP response body of the forwarded request\\'s response received from the underlying integration\\'s API. This field may be null in the case where the upstream system\\'s response is empty.'\n        },\n        headers: {\n          type: 'object',\n          description: 'The HTTP headers of the forwarded request\\'s response, exactly as received from the underlying integration\\'s API.',\n          additionalProperties: true\n        }\n      },\n      required: [        'request',\n        'statusCode'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -32,23 +37,40 @@ export const tool: Tool = {
         description:
           'The body for the forwarded request. This value must be specified as either a string or a valid JSON object.',
       },
-      headers: {
+      params: {
         type: 'object',
         description:
-          'The HTTP headers to include on the forwarded request. This value must be specified as an object of key-value pairs. Example: `{"Content-Type": "application/xml", "X-API-Version": "v1" }`',
+          'The query parameters for the forwarded request. This value must be specified as a valid JSON object rather than a query string.',
+        additionalProperties: true,
       },
-      params: {
+      request_headers: {
         type: 'object',
         description:
-          'The query parameters for the forwarded request. This value must be specified as a valid JSON object rather than a query string.',
+          'The HTTP headers to include on the forwarded request. This value must be specified as an object of key-value pairs. Example: `{"Content-Type": "application/xml", "X-API-Version": "v1" }`',
+        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: ['method', 'route'],
   },
+  annotations: {},
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.requestForwarding.forward(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.requestForwarding.forward(body)));
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/sandbox/company/update-sandbox-company.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: 'sandbox.company',
   operation: 'write',
   tags: [],
+  httpMethod: 'put',
+  httpPath: '/sandbox/company',
+  operationId: 'put-sandbox-company',
 };
 
 export const tool: Tool = {
   name: 'update_sandbox_company',
-  description: "Update a sandbox company's 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\nUpdate a sandbox company's data\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/company_update_response',\n  $defs: {\n    company_update_response: {\n      type: 'object',\n      properties: {\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          }\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              }\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        },\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: [        '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: {
@@ -45,7 +51,6 @@ export const tool: Tool = {
                 "A nine-digit code that's based on the U.S. Bank location where your account was opened.",
             },
           },
-          required: [],
         },
       },
       departments: {
@@ -67,10 +72,8 @@ export const tool: Tool = {
                   description: "The parent department's name.",
                 },
               },
-              required: [],
             },
           },
-          required: [],
         },
       },
       ein: {
@@ -92,7 +95,6 @@ export const tool: Tool = {
             enum: ['llc', 'lp', 'corporation', 'sole_proprietor', 'non_profit', 'partnership', 'cooperative'],
           },
         },
-        required: [],
       },
       legal_name: {
         type: 'string',
@@ -113,7 +115,23 @@ export const tool: Tool = {
         description:
           'The phone number of the main administrator on the account. Format: E.164, with extension where applicable, e.g. `+NNNNNNNNNNN xExtension`',
       },
+      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: [
+      'accounts',
+      'departments',
+      'ein',
+      'entity',
+      'legal_name',
+      'locations',
+      'primary_email',
+      'primary_phone_number',
+    ],
     $defs: {
       location: {
         type: 'object',
@@ -154,11 +172,21 @@ export const tool: Tool = {
       },
     },
   },
+  annotations: {
+    idempotentHint: true,
+  },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.sandbox.company.update(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.sandbox.company.update(body)));
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/sandbox/connections/accounts/create-connections-sandbox-accounts.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: 'sandbox.connections.accounts',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/sandbox/connections/accounts',
+  operationId: 'post-sandbox-connections-accounts',
 };
 
 export const tool: Tool = {
   name: 'create_connections_sandbox_accounts',
-  description: 'Create a new account for an existing connection (company/provider pair)',
+  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\nCreate a new account for an existing connection (company/provider pair)\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/account_create_response',\n  $defs: {\n    account_create_response: {\n      type: 'object',\n      properties: {\n        access_token: {\n          type: 'string'\n        },\n        account_id: {\n          type: 'string',\n          description: '[DEPRECATED] Use `connection_id` to associate a connection with an access token'\n        },\n        authentication_type: {\n          type: 'string',\n          title: 'AuthenticationType',\n          enum: [            'credential',\n            'api_token',\n            'oauth',\n            'assisted'\n          ]\n        },\n        company_id: {\n          type: 'string',\n          description: '[DEPRECATED] Use `connection_id` to associate a connection with an access token'\n        },\n        connection_id: {\n          type: 'string',\n          description: 'The ID of the new connection'\n        },\n        products: {\n          type: 'array',\n          items: {\n            type: 'string'\n          }\n        },\n        provider_id: {\n          type: 'string',\n          description: 'The ID of the provider associated with the `access_token`'\n        }\n      },\n      required: [        'access_token',\n        'account_id',\n        'authentication_type',\n        'company_id',\n        'connection_id',\n        'products',\n        'provider_id'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -36,13 +42,30 @@ 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: ['company_id', 'provider_id'],
   },
+  annotations: {},
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.sandbox.connections.accounts.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.sandbox.connections.accounts.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/sandbox/connections/accounts/update-connections-sandbox-accounts.ts

@@ -1,39 +1,62 @@
 // 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: 'sandbox.connections.accounts',
   operation: 'write',
   tags: [],
+  httpMethod: 'put',
+  httpPath: '/sandbox/connections/accounts',
+  operationId: 'put-sandbox-connections-accounts',
 };
 
 export const tool: Tool = {
   name: 'update_connections_sandbox_accounts',
   description:
-    'Update an existing sandbox account. Change the connection status to understand how the Finch API responds.',
+    "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\nUpdate an existing sandbox account. Change the connection status to understand how the Finch API responds.\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/account_update_response',\n  $defs: {\n    account_update_response: {\n      type: 'object',\n      properties: {\n        account_id: {\n          type: 'string',\n          description: '[DEPRECATED] Use `connection_id` to associate a connection with an access token'\n        },\n        authentication_type: {\n          type: 'string',\n          title: 'AuthenticationType',\n          enum: [            'credential',\n            'api_token',\n            'oauth',\n            'assisted'\n          ]\n        },\n        company_id: {\n          type: 'string',\n          description: '[DEPRECATED] Use `connection_id` to associate a connection with an access token'\n        },\n        products: {\n          type: 'array',\n          items: {\n            type: 'string'\n          }\n        },\n        provider_id: {\n          type: 'string',\n          description: 'The ID of the provider associated with the `access_token`'\n        },\n        connection_id: {\n          type: 'string',\n          description: 'The ID of the new connection'\n        }\n      },\n      required: [        'account_id',\n        'authentication_type',\n        'company_id',\n        'products',\n        'provider_id'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
       connection_status: {
         $ref: '#/$defs/connection_status_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: [],
     $defs: {
       connection_status_type: {
         type: 'string',
-        title: 'ConnectionStatus',
         enum: ['pending', 'processing', 'connected', 'error_no_account_setup', 'error_permissions', 'reauth'],
       },
     },
   },
+  annotations: {
+    idempotentHint: true,
+  },
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.sandbox.connections.accounts.update(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.sandbox.connections.accounts.update(body)),
+    );
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };

package/src/tools/sandbox/connections/create-sandbox-connections.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: 'sandbox.connections',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/sandbox/connections',
+  operationId: 'post-sandbox-connections',
 };
 
 export const tool: Tool = {
   name: 'create_sandbox_connections',
-  description: 'Create a new connection (new company/provider pair) with a new account',
+  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\nCreate a new connection (new company/provider pair) with a new account\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/connection_create_response',\n  $defs: {\n    connection_create_response: {\n      type: 'object',\n      properties: {\n        access_token: {\n          type: 'string'\n        },\n        account_id: {\n          type: 'string',\n          description: '[DEPRECATED] Use `connection_id` to associate a connection with an access token'\n        },\n        authentication_type: {\n          type: 'string',\n          title: 'AuthenticationType',\n          enum: [            'credential',\n            'api_token',\n            'oauth',\n            'assisted'\n          ]\n        },\n        company_id: {\n          type: 'string',\n          description: '[DEPRECATED] Use `connection_id` to associate a connection with an access token'\n        },\n        connection_id: {\n          type: 'string',\n          description: 'The ID of the new connection'\n        },\n        products: {\n          type: 'array',\n          items: {\n            type: 'string'\n          }\n        },\n        provider_id: {\n          type: 'string',\n          description: 'The ID of the provider associated with the `access_token`.'\n        },\n        token_type: {\n          type: 'string'\n        }\n      },\n      required: [        'access_token',\n        'account_id',\n        'authentication_type',\n        'company_id',\n        'connection_id',\n        'products',\n        'provider_id'\n      ]\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -36,13 +42,28 @@ 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: ['provider_id'],
   },
+  annotations: {},
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.sandbox.connections.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.sandbox.connections.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/sandbox/directory/create-sandbox-directory.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: 'sandbox.directory',
   operation: 'write',
   tags: [],
+  httpMethod: 'post',
+  httpPath: '/sandbox/directory',
+  operationId: 'post-sandbox-directory',
 };
 
 export const tool: Tool = {
   name: 'create_sandbox_directory',
-  description: 'Add new individuals to a sandbox 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\nAdd new individuals to a sandbox company\n\n# Response Schema\n```json\n{\n  $ref: '#/$defs/directory_create_response',\n  $defs: {\n    directory_create_response: {\n      type: 'array',\n      description: 'The individuals which were created',\n      items: {\n        type: 'object',\n        additionalProperties: true\n      }\n    }\n  }\n}\n```",
   inputSchema: {
     type: 'object',
     properties: {
@@ -39,9 +45,9 @@ export const tool: Tool = {
                   },
                   value: {
                     type: 'object',
+                    additionalProperties: true,
                   },
                 },
-                required: [],
               },
             },
             department: {
@@ -53,7 +59,6 @@ export const tool: Tool = {
                   description: 'The name of the department associated with the individual.',
                 },
               },
-              required: [],
             },
             dob: {
               type: 'string',
@@ -72,7 +77,6 @@ export const tool: Tool = {
                     enum: ['work', 'personal'],
                   },
                 },
-                required: [],
               },
             },
             employment: {
@@ -91,7 +95,6 @@ export const tool: Tool = {
                   enum: ['employee', 'contractor'],
                 },
               },
-              required: [],
             },
             employment_status: {
               type: 'string',
@@ -165,7 +168,6 @@ export const tool: Tool = {
                   description: 'A stable Finch `id` (UUID v4) for an individual in the company.',
                 },
               },
-              required: [],
             },
             middle_name: {
               type: 'string',
@@ -184,7 +186,6 @@ export const tool: Tool = {
                     enum: ['work', 'personal'],
                   },
                 },
-                required: [],
               },
             },
             preferred_name: {
@@ -212,10 +213,16 @@ export const tool: Tool = {
               description: 'The current title of the individual.',
             },
           },
-          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: [],
     $defs: {
       income: {
         type: 'object',
@@ -234,6 +241,7 @@ export const tool: Tool = {
           effective_date: {
             type: 'string',
             description: 'The date the income amount went into effect.',
+            format: 'date',
           },
           unit: {
             type: 'string',
@@ -293,11 +301,19 @@ export const tool: Tool = {
       },
     },
   },
+  annotations: {},
 };
 
-export const handler = (client: Finch, args: Record<string, unknown> | undefined) => {
-  const body = args as any;
-  return client.sandbox.directory.create(body['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.sandbox.directory.create(body)));
+  } catch (error) {
+    if (error instanceof Finch.APIError || isJqError(error)) {
+      return asErrorResult(error.message);
+    }
+    throw error;
+  }
 };
 
 export default { metadata, tool, handler };