Symptom: A tool call returns HTTP 400 or an MCP error with a message like "missing required field" or "invalid parameter value."

Cause: A required parameter was not provided, a parameter value has the wrong type, or an enum value is not in the allowed set.

Solution:

1. Use describe_method (MCP) or check the Tool Reference to confirm which parameters are required and what types are expected.
2. For REST calls, check the OpenAPI spec at https://app.ferrule.io/api/v1/{"{service}"}/openapi.json for the exact request schema.
3. Path parameters must be URL-encoded if they contain special characters.
4. Date and date-time fields typically require ISO 8601 format (e.g., 2024-01-15 or 2024-01-15T10:30:00Z).
5. For list endpoints that accept comma-separated values, pass the items as an array — Ferrule serializes them automatically.

Symptom: A tool returns "not found" or HTTP 404 for a resource you believe exists.

Cause: The resource ID is incorrect, the resource belongs to a different organization or account than the one Ferrule is authenticated for, or the resource has been deleted.

Solution:

1. Verify the ID by first calling a list tool to retrieve current IDs from the upstream service.
2. Confirm the integration is connected to the correct account. If your firm has multiple accounts with the same provider (e.g., two Clio accounts), make sure Ferrule is connected to the right one.
3. For path-parameterized URLs, double-check that the correct segment is filled in (e.g., matterId vs contactId).
4. Some providers return 404 instead of 403 when the resource exists but the token's account does not have access to it.

Symptom: Tools return HTTP 500 or an error message mentioning an "upstream" or "internal" failure, but the request looks correct.

Cause: The third-party API is experiencing an outage or returning unexpected responses that Ferrule cannot parse.

Solution:

1. Check the provider's status page (e.g., status.clio.com, status.slack.com) to see if there is an active incident.
2. Wait a few minutes and retry. Provider outages are usually brief.
3. If the error persists and the provider's status page shows no incident, contact Ferrule support with the failing request details and timestamp.

Symptom: An MCP call returns "method not found" or the AI assistant reports the tool does not exist.

Cause: The integration is either not connected, not enabled in your organization, or the method name is misspelled.

Solution:

1. Open Dashboard → Integrations and confirm the integration is connected and shows a green status indicator.
2. Confirm MCP is enabled for the integration under Configure → Protocols. MCP is on by default, but it may have been toggled off.
3. Method names are case-sensitive and use snake_case. Use describe_method with the service argument to list available methods:

   {
     "method": "tools/call",
     "params": {
       "name": "describe_method",
       "arguments": { "service": "clio" }
     }
   }

4. If your custom role does not include the integration, tools for that integration will not appear in the tool list. Ask an admin to update your role. See Organizations & Teams.

Symptom: A tool call succeeds at the HTTP level but returns an error or empty result where you expected structured data.

Cause: The upstream API returned a response that does not match the Zod schema Ferrule uses for validation. This can happen after the provider changes their API response format without notice.

Solution:

1. Check whether the provider has recently updated their API. Review their changelog or release notes.
2. For OpenAPI-generated integrations, Ferrule uses strict schema validation. If the provider added required fields or changed field types, the schema may need updating.
3. Report the mismatch to Ferrule support with the tool name, the service, and a description of what the upstream API now returns. Schema updates are quick fixes.
4. As a temporary workaround, use the REST endpoint for the same operation — some tools return raw JSON in REST mode when validation is bypassed.

Symptom: When iterating through pages of results, you receive duplicate records or skip some items between pages.

Cause: You are mixing offset-based pagination parameters (page, per_page) with cursor-based parameters (next_page_token, cursor). Using both, or changing sort order between pages, causes inconsistent results.

Solution:

1. Check the Tool Reference for the specific tool to see which pagination style it uses. Offset-based and cursor-based tools are documented separately.
2. For cursor-based tools, always pass the next_page_token or cursor value from the previous response. Do not modify other parameters between pages.
3. Do not change sort order or filters mid-pagination — start a new page sequence from page 1 if you need to change the query.