Skip to main content
Human guide: work with your agent → Inspect one Icypeas action before starting provider-backed work. Your first result is a verified input and output contract.

​
Provider-specific requirements

  • Always start with counts. Run icypeas_count_people or icypeas_count_companies before paid find operations. These are free and let you estimate result volume, refine filters, and avoid wasting credits on overly broad queries.
  • Email search is async. icypeas_email_search returns a SCHEDULED status immediately. Poll icypeas_read_results with the returned _id to get the final email. Plan for this delay in workflows.
  • Use bulk search for volume. When processing more than a handful of records, prefer icypeas_bulk_search over individual icypeas_email_search calls. Bulk supports up to 5,000 rows per batch. Monitor progress via icypeas_read_bulk_files.
  • Verify before sending. Always run icypeas_email_verification on discovered emails before outbound. Verification is inexpensive relative to search. Treat NOT_FOUND and DEBITED_NOT_FOUND as non-deliverable.
  • LinkedIn scraping is powerful but costs more. icypeas_scrape_profile returns rich contact data including phone numbers and verified emails. icypeas_scrape_company is cheaper for company-level data.
  • Find-people supports 16 filters. Use include/exclude arrays for precise targeting: job title, company, location, skills, languages, school, keywords, and more. Start broad with count, then narrow.
  • Pagination uses token-based cursors. For icypeas_find_people and icypeas_find_companies, pass the token from the previous response into the next request’s pagination.token. Page size max is 200.
  • Free operations for planning: icypeas_count_people, icypeas_count_companies, icypeas_read_results, and icypeas_read_bulk_files are free. Use them liberally.
  • Check account status. Use your internal usage dashboard before large operations.

​
Find an applicable action

Confirm your effective workspace, then search the live catalog:
Search returns candidates. Check the returned provider and operation rather than selecting a similar title automatically.

​
Inspect the selected contract

Replace <returned-tool-id> with the identifier returned by discovery:
These commands do not execute the selected provider action. Read its required inputs, supported access mode, pricing unit, outputs, and limits. A connection does not establish that every action supports BYOK. Follow the provider-specific requirements above and the live action contract.

​
Prepare one reviewed input

Use one authorized record that matches the inspected schema. Preserve its source identity and define the result you will accept. Open the action reference for its payload and response shape. Provider-backed execution can incur usage or external effects. For reusable logic, follow Write Plays. For direct-call recovery, use Tool execution recovery.
Continue only when the workspace, provider, required fields, acceptance rule, and applicable price are understood. Keep unavailable access separate from no-result evidence.