Output schemas not formally documented. Tool descriptions include expected return fields in prose ('returns job title, company, email...') but there is no JSON Schema definition visible for outputs. LLMs cannot plan downstream tool chains or extract fields reliably without structured output schemas.
Minimal error handling guidance. No tool descriptions explain what the LLM should do if a lookup fails (e.g., 'If no enrichment data found, try with a different identifier'). No distinction between retryable (rate limit) vs. non-retryable (invalid input) errors.
clay_enrich_person
Recommendations
Add formal JSON Schema definitions for all tool outputs. Example: clay_enrich_person should document { type: 'object', properties: { fullName: {type: 'string'}, jobTitle: {type: 'string'}, company: {type: 'string'}, ... }, required: [...] }. This enables LLMs to plan chaining and extract fields reliably.
Expand descriptions for Gong and ZoomInfo tools from 45-55 chars to 100-150 chars. Include: What does this reveal? When should the LLM pick this vs. a similar tool? Example: 'gong_get_transcript: Retrieves the verbatim conversation from a recorded call, including timestamps and speaker labels. Use this to analyze negotiation tactics or find commitments made. Requires a valid call_id from gong_search_calls.'
Formalize parameter interdependencies in Zod schemas using `.refine()` or `.superRefine()`. For clay_enrich_person, add: .refine(data => data.email || data.linkedin_url || (data.first_name && data.last_name), 'Must provide email, linkedin_url, or both first_name and last_name'). This moves validation out of prose and into code.
Add error recovery guidance to all tool descriptions. Example for gong_search_calls: 'If no results returned, try broadening the date range or searching by participant name instead of keywords.' This teaches the LLM to self-correct on empty results.
Document pagination strategy. Add to all search tools: 'Results are paginated (default limit=20, max=100). Call this tool again with offset=<next_offset> to retrieve the next page.' Return next_offset or has_more flag in responses if not already present.
Parameter interdependencies underspecified. Tools like clay_enrich_person accept multiple lookup keys (email, linkedin_url, first_name+last_name+company_domain) with the note 'Provide at least one' in the prose description, but the actual Zod schema does not enforce these constraints, LLMs may pass zero parameters or invalid combinations without clear feedback.
Gong and ZoomInfo tools have minimal descriptions (45-55 chars). Descriptions like 'Retrieve the full transcript of a Gong call recording by call ID' lack context on when/why to use this tool vs. alternatives, when enrichment is included, or what to do if a call_id is invalid.
Search tools lack pagination clarity. gong_search_calls, zoominfo_search_company, zoominfo_search_contact, linkedin_search_leads, and linkedin_search_companies all accept a 'limit' parameter (default 20, max 100) but do not document how to retrieve the next page (no cursor, offset, or page_number returned in visible code). Large result sets risk context window exhaustion.
Parameter descriptions are often terse (10-40 chars). Examples: 'Search query' (13 chars), 'Company name' (12 chars), 'Email address' (13 chars). These lack format/constraint guidance. A description should clarify: Is the email format validated? Does company_name accept partial matches or require exact match?
Missing composition hints. If an LLM searches for a lead on LinkedIn, it cannot know without additional context whether it should then call clay_enrich_person or zoominfo_search_contact to get richer data. No tool explicitly documents common sequences or prerequisite lookups (e.g., 'Call this tool first to locate the contact before enriching').
Expand parameter descriptions to 50-100 chars with format/constraint hints. Example for company_name: 'Company name (partial matches accepted, e.g., "Acme" returns "Acme Corp" and "Acme Solutions"). Exact match recommended for single result.'
Add tool composition hints. Example in clay_enrich_person description: 'To enrich a list of leads found via linkedin_search_leads, loop this tool over the linkedin_url or email from each lead.' This guides multi-step workflows.
Document which tools are idempotent and safe to retry. Add to tool descriptions: 'Idempotent: Safe to retry on transient failures (rate limits, timeouts). No side effects.' vs. 'Stateful: May create duplicates if retried, use clay_trigger_enrichment with idempotency keys instead.'
Add explicit guidance on identifier precedence. Example for linkedin_get_profile: 'Lookup priority: 1. profile_id (fastest), 2. email (most reliable), 3. first_name + last_name (slowest, may return multiple matches). Provide the highest-priority identifier available.'
Clarify which fields are always present vs. optional in returned data. Example: 'Returns: { fullName (optional), jobTitle (optional), company (optional), email (required if found), linkedInUrl (optional) }...' This helps LLMs decide whether to retry or proceed with partial data.