Company actions
Tools that create companies, attach files, run company actions, cast Inbox votes, and propose reviewable company changes.
These tools change company data. Most of them write immediately, with no
approval step inside DealTraq. Only
propose_company_changes creates a proposal for
review.
Ask for writes explicitly
Your assistant should change DealTraq data only when you ask it to. Every
write tool takes an idempotencyKey, so a retried call with the same key
and input returns the first result instead of writing twice. See
How writes work.
list_company_action_capabilities
Read · Cost 1
Lists every company action your assistant can run, what it does, whether it is destructive, and which input fields it requires. Your assistant uses this to pick the right action and the right tool.
This tool takes no inputs.
Example: What can you change on a company in DealTraq?
Action catalog
| Action | What it does | Destructive |
|---|---|---|
company.vote.set | Saves or clears your personal Inbox vote. Prefer set_my_inbox_vote. | No |
company.inbox_vote.apply | Applies the team's Inbox votes. If votes disagree, you choose the outcome (LEAD or ARCHIVED) after reviewing them. | No |
company.profile.update | Edits company fields, links, lead, and custom-field values. | No |
company.stage.transition | Moves a company to another pipeline stage, including the Archived stage. | No |
company.note.create | Adds a company note. | No |
company.note.update | Edits a company note. | No |
company.note.delete | Deletes a company note. | Yes |
company.founder.create | Adds a founder. | No |
company.founder.update | Edits a founder. | No |
company.founder.delete | Deletes a founder. | Yes |
company.contact.upsert | Creates or updates a company contact. | No |
company.contact.delete | Deletes a company contact. | Yes |
company.category.assign | Assigns a category. | No |
company.category.unassign | Removes a category. | Yes |
company.team.assign | Assigns a member to the company team, optionally with a role. | No |
company.team.unassign | Removes a team assignment. | Yes |
company.custom_field_definition.create | Creates a company custom field. | No |
company.custom_field_definition.update | Edits a custom field's label or configuration. | No |
company.custom_field_definition.archive | Archives a custom field. | Yes |
company.custom_field_option.create | Adds an option to a choice-type custom field. | No |
company.custom_field_option.update | Edits a custom-field option. | No |
company.custom_field_option.delete | Deletes a custom-field option. | Yes |
company.archive | Soft-deletes the company record. This is not the Archived pipeline stage. | Yes |
company.restore | Restores a soft-deleted company. | No |
company.merge | Merges one company into another and soft-deletes the source. | Yes |
company.task.create | Creates a task linked to the company. | No |
company.task.update | Edits a task's status, schedule, visibility, assignees, or archive state. | No |
company.task_comment.create | Adds a comment or reply to a task. | No |
company.task_comment.update | Edits a comment you wrote. | No |
company.task_comment.delete | Deletes a comment you wrote. | Yes |
company.scoring_feedback.create | Adds feedback used in future company scoring. | No |
company.meeting.move | Moves a meeting from one company to another. | No |
Archive versus the Archived stage
To pass on a company and move it to your CRM's Archived stage, use
company.stage.transition. company.archive removes the company record
from DealTraq views (it can be restored with company.restore).
create_company
Write — immediate · Cost 10
Adds a new company to DealTraq, optionally in a specific stage and with a
lead. If DealTraq matches the request to a company that already exists, it
returns that company (matchedExisting: true) instead of creating a
duplicate.
| Input | Type | Required | Description |
|---|---|---|---|
name | string, up to 500 characters | Yes | Company name. |
idempotencyKey | string, 8 to 200 characters | Yes | Stable key for this creation. |
description | string, up to 20,000 characters | No | Factual summary: what the company builds, for whom, and where it comes from. Put opinions and thesis fit in a note instead. |
websiteUrl | URL | No | Company website. |
stageId | UUID | No | Stage to place the company in. |
leadOrgMemberId | UUID | No | Member to set as lead. |
founderNames | string | No | Founder names. |
source, sourceLink | string, URL | No | Where the deal came from. |
meetingNotesLink, driveLink, metadataLink | URL | No | Related links. |
customFields | object | No | Custom-field values. |
Example: Add Acme Robotics (acmerobotics.com) to our Inbox, sourced from the YC demo day list.
add_company_file
Write — immediate · Cost 20
Attaches one file from your conversation to a company, optionally inside an existing company folder. The result confirms the file name, type, and size but never echoes the content or returns a storage link.
| Input | Type | Required | Description |
|---|---|---|---|
companyId | UUID | Yes | The company to attach the file to. |
fileName | string, up to 255 characters | Yes | File name, without folder paths. |
mimeType | string | Yes | File type, such as application/pdf. |
contentBase64 | string | Yes | File content, base64-encoded. |
idempotencyKey | string, 8 to 200 characters | Yes | Stable key for this upload. |
folderId | UUID | No | Existing company folder to put the file in. |
isCompanyDeck | boolean | No | Mark the file as the company's deck. |
Notes
- Files must be non-empty and at most 5 MiB.
Example: Attach this pitch deck PDF to Acme and mark it as their deck.
execute_non_destructive_company_action
Write — immediate · Cost 10
Runs one action from the catalog that is marked non-destructive, such as adding a note, updating the profile, moving a stage, or creating a task. The change takes effect immediately.
| Input | Type | Required | Description |
|---|---|---|---|
request.action | action name | Yes | A non-destructive action from the catalog. |
request.input | object | Yes | The action's input. Required fields are listed by list_company_action_capabilities. |
idempotencyKey | string, 8 to 200 characters | Yes | Stable key for this change. |
Notes
- Some actions require the company's current
updatedAt(fromget_company) so they fail rather than overwrite a newer change.
Example: Add a note to Acme summarizing today's call, and move it to Due Diligence.
execute_typed_company_action
Write — destructive · Cost 10
Runs any action from the catalog, including deleting notes, founders, or contacts, soft-deleting a company, and merging companies. The change takes effect immediately, with no approval step in DealTraq.
| Input | Type | Required | Description |
|---|---|---|---|
request.action | action name | Yes | Any action from the catalog. |
request.input | object | Yes | The action's input. |
idempotencyKey | string, 8 to 200 characters | Yes | Stable key for this change. |
Notes
- Applying team Inbox votes (
company.inbox_vote.apply) runs through this tool. If votes disagree, the first call returns the votes; after you chooseLEADorARCHIVED, your assistant retries with your decision and the returnedreviewedVotestoken.
Example: Merge "Acme Inc" into "Acme Robotics"; they're the same company.
execute_company_action
Write — destructive · Cost 10
An older form of execute_typed_company_action, kept for existing clients. It
runs any catalog action immediately but takes the action input as an untyped
object, so clients see less about each action's fields. New integrations
should use the typed tools.
| Input | Type | Required | Description |
|---|---|---|---|
action | action name | Yes | Any action from the catalog. |
input | object | Yes | The action's input. |
idempotencyKey | string, 8 to 200 characters | Yes | Stable key for this change. |
Example: Delete the duplicate founder entry on Acme.
get_my_inbox_vote
Read · Cost 2
Shows your own pending Inbox vote on a company (direction, reasons, and note) and the company's current stage. Your assistant reads this before and after setting a vote.
| Input | Type | Required | Description |
|---|---|---|---|
companyId | UUID | Yes | The company to check. |
Example: Did I already vote on Acme?
set_my_inbox_vote
Write — immediate · Cost 10
Casts or clears your personal Inbox vote on a company. Your vote is pending until the team's votes are applied; it does not move the company.
UPVOTE(Proceed) also adds you to the company team.DOWNVOTE(Archive) also removes your team assignments on the company.CLEARremoves your vote and leaves team assignments unchanged.
| Input | Type | Required | Description |
|---|---|---|---|
companyId | UUID | Yes | The company to vote on. |
vote | UPVOTE, DOWNVOTE, or CLEAR | Yes | Your vote. |
research | object | For UPVOTE and DOWNVOTE | The research behind the vote: schemaVersion: "company-research/v1", the full reportMarkdown with [source:key] citations, up to 20 keyed sources, gaps, and an optional summary. Omit for CLEAR. |
reasons | array, up to 10 | No | Vote reasons. Kept from your previous vote if you repeat the same direction without them. |
note | string, up to 1,000 characters | No | A short note. Kept from your previous vote if omitted. |
idempotencyKey | string, 8 to 200 characters | Yes | Stable key for this vote. |
Notes
- The research report is saved with the vote as unverified, agent-written
research (up to 64 KB). It does not create notes or update company fields.
Read it later with
read_company_research_submission. - If no sources were inspected, the report must say so in
gaps. - Applying the team's votes is a separate action (
company.inbox_vote.apply) that you must ask for explicitly.
Example: Upvote Acme for me. Strong team and the market fits our thesis.
propose_company_changes
Write — proposal only · Cost 8
Creates a proposal to change a company's profile, its stage, or both, and returns a DealTraq link where it can be reviewed and approved. No company data changes during this call. The change runs only after approval inside DealTraq.
| Input | Type | Required | Description |
|---|---|---|---|
companyId | UUID | Yes | The company to change. |
expectedUpdatedAt | ISO date-time | Yes | The company's updatedAt from get_company. The proposal is rejected if the company changed since. |
stageId | UUID | One of stageId or profile | The stage to move the company to. |
profile | object | One of stageId or profile | Field changes: name, description, websiteUrl, founderNames, leadOrgMemberId, source, sourceLink, links, and customFields. |
reason | string, up to 2,000 characters | No | Why the change is proposed, shown to the reviewer. |
idempotencyKey | string, 8 to 200 characters | Yes | Stable key for this proposal. |
Notes
- A profile change and a stage change become separate items in one proposal group, so each can be reviewed on its own.
Example: Propose moving Acme to Due Diligence, but don't apply the change directly.
get_company_change_proposal
Read · Cost 2
Returns the current status of a proposal created through MCP, with its approval link and the status of each item in the group. It never changes the proposal.
| Input | Type | Required | Description |
|---|---|---|---|
proposalId | UUID | Yes | The proposal to check. |
Notes
- Statuses are
PROPOSED,APPROVED,REJECTED,EXECUTING,EXECUTED,FAILED,CANCELLED, andSUPERSEDED. When items in one group differ, the group status isMIXED;mutationExecutedistrueonce any item has executed. - You can read your own proposals. Organization owners and admins can read any MCP proposal in the organization.
Example: Has the Acme stage-change proposal been approved yet?