Instructions for AI agents

This page is written for AI agents using the Icebreaker MCP server. People can point their agent here with: "Read docs.icebreaker.xyz/docs/agent-instructions and follow it."

The server also returns these rules from get_server_instructions. If they differ, follow the server.

Reading these docs

• Page index: llms.txt
• Any page as markdown: add .md to its URL, like docs.icebreaker.xyz/docs/concepts.md
• Tool reference: Available tools
• Terms: Key concepts

Getting started with a user

1. Call lookup_viewer_tool and check linked_accounts before asking the user to link anything.
2. Call get_started only if nothing is linked, the user asks how to connect, or a search comes back empty.
3. Call get_entitlements_tool once to learn the user's plan and teams.

Search defaults

Use search_network first. On every search, set:

{ "hideViewer": true, "sources": ["all"], "ordinality": ["1st", "2nd"] }

• Put role, skills, and location in one globs string, like ["rust engineer San Francisco"].
• For a company, add credentialnames:Verified: company.com to globs. For several companies, set allowAnyCredential: true.
• Use ["Global"] only to look up one profile by handle, search another person's network, or search a team via get_team_tool.
• Results cap at 100 per call. Paginate with offset.

Scope

• Omit teamDomainScope for personal scope. Pass the team domain, like acme.com, for team scope.
• Never assume team scope. Use it when the user says "our team" or is on a paid team and the tool needs Starter or higher.
• If a plan gate refuses a call, the refusal may list teams the user can use. Retry with one of them.

Quality rules

• When asked for a role, check the bio describes the person as that role, not someone who works with it. Leave out recruiters, sales, and BD unless asked for.
• Prefer 10 strong results over 50 mixed ones. Say when you're unsure.
• Always include each person's profile_url. If it's missing, build it from omni_profile.social_name.

Actions that change state

Ask the user before you queue or cancel syncs, enrich, upload CSVs, edit lists, save monitors, or invite collaborators. Collaborator tools send email.

• A queued sync isn't a finished sync. Check queue_network_sync_status_tool and don't requeue automatically.
• Enrichment is async. Wait 30 to 60 seconds before calling get_enrichment_result_tool.

Never

• Ask for or set viewerPkid. Viewer context comes from the session.
• Invent profile links, connections, or contact details.
• Present a person without a link.

Ready-made skills

The Cookbook has tested skills for sourcing, list building, syncs, and monitors.