contacts:read, contacts:write and research:run, which you grant on the Authorize access page when you connect.
This page is generated from the connector’s tool catalogue. It describes 16 tools. Every tool reads or writes only your own account.
Permissions this page needs
contacts:read: Read your contacts, network information and research resultscontacts:write: Add contacts, update the notes and tags on your contacts, and change their details and status after you approve each changeresearch:run: Start research on your contacts that uses credits, after you approve each batch in the browser
contacts.list
Your agent host shows this tool as “List contacts”.
List every authenticated student contact, including DO_NOT_CONTACT records, with measured pagination.
Permissions: This tool needs contacts:read, which the Authorize access page describes as “Read your contacts, network information and research results”.
Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.
Input
Example call
contacts.list input
Result
A result is never larger than 49,152 bytes. If the stored value does not fit, the tool returns a measured fragment and a cursor for the next one. This tool’s result takes one of these 2 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.Shape 1
Shape 1
Top-level fields
Shape 2
Shape 2
Top-level fields
Errors
A failed call returns one protocol error with no error code, and its text isTool call failed. every time. This tool looks up no record by id, so it never sends a text that names a record. The error codes page gives every text a read failure can carry.
contacts.get
Your agent host shows this tool as “Get contact”.
Read one authenticated student contact by id or its owner-scoped generated slug.
Permissions: This tool needs contacts:read, which the Authorize access page describes as “Read your contacts, network information and research results”.
Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.
Input
The agent sends one object, and the table below is that object exactly as the connector publishes it. The connector accepts the object in one of these 2 forms and refuses any mixture of them. A published schema cannot state that rule, which is why the Required column readsno on every property and why each form is written out under the table. Within a form, every property the form does not name is refused.
Form 1, sending id
Send id. It is required in this form. cursor may be sent beside it, and nothing else may be.
Form 2, sending slug
Send slug. It is required in this form. cursor may be sent beside it, and nothing else may be.
Example calls
Result
A result is never larger than 49,152 bytes. If the stored value does not fit, the tool returns a measured fragment and a cursor for the next one. This tool’s result takes one of these 2 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.Shape 1
Shape 1
Top-level fields
Shape 2
Shape 2
Top-level fields
Errors
A failed call returns one protocol error with no error code. Its text isTool call failed. in every case but one: a call that finds no contact of yours says so and tells the agent to call the matching list tool. The error codes page quotes that text in full and lists the eight kinds of record it can name.
contacts.notes.get
Your agent host shows this tool as “Get contact notes”.
Read one authenticated student contact note in measured fragments.
Permissions: This tool needs contacts:read, which the Authorize access page describes as “Read your contacts, network information and research results”.
Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.
Input
Example call
contacts.notes.get input
Result
A result is never larger than 49,152 bytes. If the stored value does not fit, the tool returns a measured fragment and a cursor for the next one. A result carries these top-level fields:Top-level fields
Errors
A failed call returns one protocol error with no error code. Its text isTool call failed. in every case but one: a call that finds no contact of yours says so and tells the agent to call the matching list tool. The error codes page quotes that text in full and lists the eight kinds of record it can name.
contacts.tags.get
Your agent host shows this tool as “Get contact tags”.
Read every authenticated student contact tag in measured fragments.
Permissions: This tool needs contacts:read, which the Authorize access page describes as “Read your contacts, network information and research results”.
Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.
Input
Example call
contacts.tags.get input
Result
A result is never larger than 49,152 bytes. If the stored value does not fit, the tool returns a measured fragment and a cursor for the next one. A result carries these top-level fields:Top-level fields
Errors
A failed call returns one protocol error with no error code. Its text isTool call failed. in every case but one: a call that finds no contact of yours says so and tells the agent to call the matching list tool. The error codes page quotes that text in full and lists the eight kinds of record it can name.
contacts.stats.get
Your agent host shows this tool as “Get contact stats”.
Count every authenticated student contact, including DO_NOT_CONTACT records, by status and due follow-up state.
Permissions: This tool needs contacts:read, which the Authorize access page describes as “Read your contacts, network information and research results”.
Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.
Input
This tool takes no input.Example call
contacts.stats.get input
Result
A result is never larger than 49,152 bytes. A result carries these top-level fields:Top-level fields
Errors
A failed call returns one protocol error with no error code, and its text isTool call failed. every time. This tool looks up no record by id, so it never sends a text that names a record. The error codes page gives every text a read failure can carry.
contacts.network.stats.get
Your agent host shows this tool as “Get network stats”.
Count the authenticated student network population after excluding DO_NOT_CONTACT records.
Permissions: This tool needs contacts:read, which the Authorize access page describes as “Read your contacts, network information and research results”.
Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.
Input
This tool takes no input.Example call
contacts.network.stats.get input
Result
A result is never larger than 49,152 bytes. A result carries these top-level fields:Top-level fields
Errors
A failed call returns one protocol error with no error code, and its text isTool call failed. every time. This tool looks up no record by id, so it never sends a text that names a record. The error codes page gives every text a read failure can carry.
contacts.notes.update
Your agent host shows this tool as “Update contact notes”.
What this changes: Replace the private notes on one of the authenticated student’s own contacts, with durable idempotency.
The whole note is replaced rather than appended to, at most 8000 characters, and the write fails without changing anything if anybody edited that contact’s notes first.
Permissions: This tool needs contacts:write, which the Authorize access page describes as “Add contacts, update the notes and tags on your contacts, and change their details and status after you approve each change”.
Risk: safe_write. This tool changes one of your own settings as soon as the agent calls it. It does not ask you to approve first, because the change affects only your own account and you can set it back yourself.
Input
Example call
contacts.notes.update input
Result
A result is never larger than 4,096 bytes. This tool’s result takes one of these 4 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.Shape 1, where tag is completed
Shape 1, where tag is completed
Top-level fields
Shape 2, where tag is accepted
Shape 2, where tag is accepted
Top-level fields
Shape 3, where status is failed
Shape 3, where status is failed
Top-level fields
Shape 4, where status is uncertain
Shape 4, where status is uncertain
Top-level fields
The result may carry a retry hint
A call can be accepted and still ask the agent to come back later. When that happens the result is an accepted result and not a failure, and it carries a hint beside it holding one of these codes and a delay in milliseconds. Nothing has gone wrong and nothing has been written yet.Errors
A call that does not succeed carries one of these codes.contacts.tags.update
Your agent host shows this tool as “Update contact tags”.
What this changes: Replace the tags on one of the authenticated student’s own contacts, with durable idempotency.
The whole list is replaced rather than merged, at most 25 tags of 60 characters each, and the write fails without changing anything if anybody edited that contact’s tags first.
Permissions: This tool needs contacts:write, which the Authorize access page describes as “Add contacts, update the notes and tags on your contacts, and change their details and status after you approve each change”.
Risk: safe_write. This tool changes one of your own settings as soon as the agent calls it. It does not ask you to approve first, because the change affects only your own account and you can set it back yourself.
Input
Example call
contacts.tags.update input
Result
A result is never larger than 4,096 bytes. This tool’s result takes one of these 4 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.Shape 1, where tag is completed
Shape 1, where tag is completed
Top-level fields
Shape 2, where tag is accepted
Shape 2, where tag is accepted
Top-level fields
Shape 3, where status is failed
Shape 3, where status is failed
Top-level fields
Shape 4, where status is uncertain
Shape 4, where status is uncertain
Top-level fields
The result may carry a retry hint
A call can be accepted and still ask the agent to come back later. When that happens the result is an accepted result and not a failure, and it carries a hint beside it holding one of these codes and a delay in milliseconds. Nothing has gone wrong and nothing has been written yet.Errors
A call that does not succeed carries one of these codes.contacts.create
Your agent host shows this tool as “Add contact”.
What this changes: Add one new person to the authenticated student’s contacts, optionally with a status and tags.
Each row reports created, duplicate or error. A row whose email or LinkedIn URL is already on one of the student’s contacts, whose name matches a contact at the same company (or a saved contact with no company), or that repeats an earlier row is a duplicate and is not added, with the existing contact’s id when known, so a repeated call adds nobody twice. The status is one of NEW, CONTACTED, REPLIED, SCHEDULED, COMPLETED, DO_NOT_CONTACT and defaults to NEW. At most 25 tags. Adding contacts uses no credits; the plan’s contact limit applies to each row, and once the student has added 200 or more contacts in the last hour, every remaining row reports rate_limited and is not added.
Permissions: This tool needs contacts:write, which the Authorize access page describes as “Add contacts, update the notes and tags on your contacts, and change their details and status after you approve each change”.
Risk: safe_write. This tool changes one of your own settings as soon as the agent calls it. It does not ask you to approve first, because the change affects only your own account and you can set it back yourself.
Input
Example call
contacts.create input
Result
A result is never larger than 32,768 bytes. A result carries these top-level fields:Top-level fields
Errors
A call that does not succeed carries one of these codes.contacts.bulk_create
Your agent host shows this tool as “Add contacts”.
What this changes: Add up to 25 new people to the authenticated student’s contacts in one call.
The optional top-level status applies to rows without their own. Each row reports created, duplicate or error. A row whose email or LinkedIn URL is already on one of the student’s contacts, whose name matches a contact at the same company (or a saved contact with no company), or that repeats an earlier row is a duplicate and is not added, with the existing contact’s id when known, so a repeated call adds nobody twice. The status is one of NEW, CONTACTED, REPLIED, SCHEDULED, COMPLETED, DO_NOT_CONTACT and defaults to NEW. At most 25 tags. Adding contacts uses no credits; the plan’s contact limit applies to each row, and once the student has added 200 or more contacts in the last hour, every remaining row reports rate_limited and is not added.
Permissions: This tool needs contacts:write, which the Authorize access page describes as “Add contacts, update the notes and tags on your contacts, and change their details and status after you approve each change”.
Risk: safe_write. This tool changes one of your own settings as soon as the agent calls it. It does not ask you to approve first, because the change affects only your own account and you can set it back yourself.
Input
Example call
contacts.bulk_create input
Result
A result is never larger than 32,768 bytes. A result carries these top-level fields:Top-level fields
Errors
A call that does not succeed carries one of these codes.contacts.import.check
Your agent host shows this tool as “Check a contacts spreadsheet”.
Check a spreadsheet before contacts.import, writing nothing. Takes the same input. Send the sheet as CSV text or as headers and rows. Convert .xlsx files to CSV first. Send csv or headers with rows, not both; rows are arrays of cells in header order. The call must fit in 2 MB and hold at most 1000 rows; split a bigger sheet. Returns which column maps to which contact field, the columns that will be ignored, and the created, skipped and failed counts contacts.import would report against the contacts the student has now, with the first 10 row errors. When the sheet cannot be imported as sent (no header it recognizes, no rows, more than 1000 rows), problem says what to fix and the counts are zero.
Permissions: This tool needs contacts:read, which the Authorize access page describes as “Read your contacts, network information and research results”.
Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.
Input
The agent sends one object, and the table below is that object exactly as the connector publishes it. The connector accepts the object in one of these 2 forms and refuses any mixture of them. A published schema cannot state that rule, which is why the Required column readsno on every property and why each form is written out under the table. Within a form, every property the form does not name is refused.
Form 1, sending csv
Send csv. It is required in this form. No other property is accepted with it.
Form 2, sending headers, rows
Send headers and rows. They are required in this form. No other property is accepted with them.
Example calls
Result
A result is never larger than 32,768 bytes. A result carries these top-level fields:Top-level fields
Errors
A failed call returns one protocol error with no error code, and its text isTool call failed. every time. This tool looks up no record by id, so it never sends a text that names a record. The error codes page gives every text a read failure can carry.
contacts.import
Your agent host shows this tool as “Import contacts from a spreadsheet”.
What this changes: Import a spreadsheet of people into the student’s contacts.
Send the sheet as CSV text or as headers and rows. Convert .xlsx files to CSV first. Send csv or headers with rows, not both; rows are arrays of cells in header order. The call must fit in 2 MB and hold at most 1000 rows; split a bigger sheet. Columns such as Name, First name, Last name, Email, Company, Title, School, LinkedIn and Phone are found by name; other columns are ignored. A row needs a name. A row matching one of the student’s contacts by email, LinkedIn URL, or name at the same company, or an earlier row, is skipped, so importing the same sheet twice adds nobody. Rows past the plan’s contact limit, or past 200 contacts added in the last hour, fail. The details stay private to the student, as with contacts.create. Returns counts (updated is always 0) and the first 10 row errors (row 1 is the first row under the header). Nothing is sent and no research starts.
Permissions: This tool needs contacts:write, which the Authorize access page describes as “Add contacts, update the notes and tags on your contacts, and change their details and status after you approve each change”.
Risk: safe_write. This tool adds people to your contacts as soon as the agent calls it. It never changes a contact you already have, and what it adds stays private to your account. It does not ask you to approve first, because it changes only your own contacts, sends nothing, and you can delete what it added yourself.
Input
The agent sends one object, and the table below is that object exactly as the connector publishes it. The connector accepts the object in one of these 2 forms and refuses any mixture of them. A published schema cannot state that rule, which is why the Required column readsno on every property and why each form is written out under the table. Within a form, every property the form does not name is refused.
Form 1, sending csv
Send csv. It is required in this form. No other property is accepted with it.
Form 2, sending headers, rows
Send headers and rows. They are required in this form. No other property is accepted with them.
Example calls
Result
A result is never larger than 32,768 bytes. A result carries these top-level fields:Top-level fields
Errors
A row that cannot be added is counted infailed with its reason, and is not a failure of the call. A call Coffee Chats refuses before importing anything, such as a sheet with more than 1000 rows or with no name column, writes nothing and returns an error whose text names what to fix. Otherwise a call that does not succeed carries this code.
contacts.update
Your agent host shows this tool as “Propose contact changes”.
What this changes: Propose changes to the details, status, rating, tags or notes of 1 to 25 of the authenticated student’s contacts, one item per contact.
Nothing changes until the student approves each change, in the approval card in Claude or ChatGPT or in a browser. A contact that changed after the student saw the changes is skipped, never overwritten. Read the outcome with contacts.update.get; calling this tool again with the same idempotencyKey returns the same proposal.
Permissions: This tool needs contacts:read, which the Authorize access page describes as “Read your contacts, network information and research results”, and contacts:write, which the Authorize access page describes as “Add contacts, update the notes and tags on your contacts, and change their details and status after you approve each change”.
Risk: consequential. This tool cannot change anything on its own. It proposes the changes, and nothing happens until you approve exactly what is shown, in the approval card in Claude or ChatGPT or on the Coffee Chats page it points to. A contact that changed after you saw the changes is left as it is.
Input
Example call
contacts.update input
Result
A result is never larger than 32,768 bytes. This tool’s result takes one of these 6 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.Shape 1, where tag is requires_confirmation
Shape 1, where tag is requires_confirmation
Top-level fields
Shape 2, where tag is completed
Shape 2, where tag is completed
Top-level fields
Shape 3, where tag is accepted
Shape 3, where tag is accepted
Top-level fields
Shape 4, where status is failed
Shape 4, where status is failed
Top-level fields
Shape 5, where status is cancelled
Shape 5, where status is cancelled
Top-level fields
Shape 6, where status is uncertain
Shape 6, where status is uncertain
Top-level fields
The result may carry a retry hint
A call can be accepted and still ask the agent to come back later. When that happens the result is an accepted result and not a failure, and it carries a hint beside it holding one of these codes and a delay in milliseconds. Nothing has gone wrong and nothing has been written yet.Errors
A call that does not succeed carries one of these codes. A call Coffee Chats refuses before proposing anything, such as a rating outside 0.5 to 5 or not in half steps, a batch too large to show for approval or a batch in which every contact would be left out, creates no review request and returns an error whose text names what to fix.contacts.update.get
Your agent host shows this tool as “Get contact update status”.
Read the state of a contact update proposed with contacts.update: waiting for approval, applying, or done with the contacts it updated and the ones it left unchanged and why. Polling here shows no approval card.
Permissions: This tool needs contacts:write, which the Authorize access page describes as “Add contacts, update the notes and tags on your contacts, and change their details and status after you approve each change”.
Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.
Input
Example call
contacts.update.get input
Result
A result is never larger than 8,192 bytes. This tool’s result takes one of these 6 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.Shape 1, where tag is requires_confirmation
Shape 1, where tag is requires_confirmation
Top-level fields
Shape 2, where tag is completed
Shape 2, where tag is completed
Top-level fields
Shape 3, where tag is accepted
Shape 3, where tag is accepted
Top-level fields
Shape 4, where status is failed
Shape 4, where status is failed
Top-level fields
Shape 5, where status is cancelled
Shape 5, where status is cancelled
Top-level fields
Shape 6, where status is uncertain
Shape 6, where status is uncertain
Top-level fields
The result may carry a retry hint
A call can be accepted and still ask the agent to come back later. When that happens the result is an accepted result and not a failure, and it carries a hint beside it holding one of these codes and a delay in milliseconds. Nothing has gone wrong and nothing has been written yet.Errors
A failed call returns one protocol error with no error code, and its text isTool call failed. every time, including for an operationId that names no review request this connection made. The error codes page gives every text a read failure can carry.
contacts.research.start
Your agent host shows this tool as “Propose contact research”.
What this changes: Start research on 1 to 25 of the authenticated student’s contacts (people only).
Research uses credits: a contact’s first research costs 5 credits, and a contact that has a booked meeting or was already charged is free. This proposes one batch with its cost and the student’s available balance; nothing starts until after the student approves the batch in the browser, which the approval card links to. Contacts with no company or LinkedIn, or already being researched, are left out. Read each contact’s research with contacts.research.get; calling this tool again with the same idempotencyKey returns the same proposal. A connection made before research was available must reconnect to grant research:run before it can use this tool.
Permissions: This tool needs contacts:read, which the Authorize access page describes as “Read your contacts, network information and research results”, and research:run, which the Authorize access page describes as “Start research on your contacts that uses credits, after you approve each batch in the browser”.
Risk: consequential. This tool cannot start research on its own. It proposes one batch with its cost in credits and your available balance, and nothing starts until you approve the batch on the Coffee Chats page it points to. Research spends credits, so it is never approved in the approval card. When the batch runs it starts no more paid research than the cost you approved, or than your balance when it starts.
Input
Example call
contacts.research.start input
Result
A result is never larger than 32,768 bytes. This tool’s result takes one of these 6 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.Shape 1, where tag is requires_confirmation
Shape 1, where tag is requires_confirmation
Top-level fields
Shape 2, where tag is completed
Shape 2, where tag is completed
Top-level fields
Shape 3, where tag is accepted
Shape 3, where tag is accepted
Top-level fields
Shape 4, where status is failed
Shape 4, where status is failed
Top-level fields
Shape 5, where status is cancelled
Shape 5, where status is cancelled
Top-level fields
Shape 6, where status is uncertain
Shape 6, where status is uncertain
Top-level fields
The result may carry a retry hint
A call can be accepted and still ask the agent to come back later. When that happens the result is an accepted result and not a failure, and it carries a hint beside it holding one of these codes and a delay in milliseconds. Nothing has gone wrong and nothing has been written yet.Errors
A call that does not succeed carries one of these codes. A call Coffee Chats refuses before proposing anything, such as a repeated contact, a batch too large to show for approval or a batch in which every contact would be left out, creates no review request and returns an error whose text names what to fix.contacts.research.get
Your agent host shows this tool as “Get contact research”.
Read the research status and research results for one of the authenticated student’s contacts. running is false when nothing is researching the contact now: a pending or in-progress run whose lease went stale keeps its status but is not running. When a report exists, report summarizes the one-pager: the executive summary, bottom line, sections and sources, with its completedAt. truncated is true when text was clipped or parts were dropped to fit the page. Polling here shows no approval card.
Permissions: This tool needs contacts:read, which the Authorize access page describes as “Read your contacts, network information and research results”.
Risk: read. This tool only reads your own data. It never changes anything and it never asks for your approval.
Input
Example call
contacts.research.get input
Result
A result is never larger than 16,384 bytes. A result carries these top-level fields:Top-level fields
Errors
A failed call returns one protocol error with no error code. Its text isTool call failed. in every case but one: a call that finds no contact of yours says so and tells the agent to call the matching list tool. The error codes page quotes that text in full and lists the eight kinds of record it can name.