Agent guide

1. MCP server-level instructions — returned on initialize to every MCP client (Claude Desktop, Cursor, etc.); the client injects it into the model’s system prompt automatically. Source: apps/mcp/src/instructions.ts.
2. AGENTS.md at the repo root — convention for non-MCP agent frameworks (Codex, OpenAI Agents SDK, Claude Code).
3. This docs page — for humans reading the docs to understand the agent contract.

​

Your 15 tools (this is the complete list)

• No task tools — use POST /tasks REST or salty CLI.
• No webhook tools — use POST /webhook-endpoints REST or salty webhooks add.
• No custom-object tools — use POST /custom-objects REST.
• No get_deal — use search_deals with a filter.
• No get_usage / get_workspace — admin UI / CLI only.
• No delete_* — by design, but DELETE is a recoverable soft-delete to a 30-day trash; restore via POST /trash/<resource>/<id>/restore (resource ∈ people, companies, deals, notes, tasks, activities, custom-objects) or the /records/trash admin UI.

​

30-second mental model

​

Rules that aren’t obvious from tool descriptions

1. No delete tools, by design. There’s no MCP delete_* tool, but nothing an agent does is irreversible: every DELETE is a recoverable soft-delete to a 30-day trash (auto-purged after 30 days). If the user explicitly asks to delete, tell them to use curl -X DELETE (REST, e.g. DELETE /people/{id}) or the /records admin UI. To undo, POST /trash/<resource>/<id>/restore (resource ∈ people, companies, deals, notes, tasks, activities, custom-objects) or use the /records/trash admin UI.
2. Money is a string-encoded bigint. deal.value_cents is JSON-string (e.g. "5000000" = $50,000.00). Currency defaults to USD; pass currency: "INR" etc. if otherwise. deal.closed_at is response-only (currently always null; v1.1 auto-sets on stage→won/lost — don’t write it).
3. Parent references use parent_object_type + parent_object_id. Notes, tasks, and activities attach to a parent via these two fields. Valid parent_object_type: person, company, deal.
4. Schema attributes need 4 fields minimum. add_attribute requires attribute_key (snake_case), display_name (Title Case), data_type, and object_type. Enum types need enum_values. Reference types need reference_object_type.
5. custom_attributes validation is LENIENT. Defined keys are validated; unknown keys pass through. Required attrs ARE enforced.
6. Webhooks return signing_secret ONCE. Webhooks are registered over REST/CLI, not MCP (there is no webhook tool). Surface the whsec_… to the user immediately on the POST /webhook-endpoints (REST) or salty webhooks add (CLI) response.
7. subscribed_events: ["*"] is the default. No glob patterns in v1.
8. Pagination is cursor-based. Pass next_cursor back as the cursor param. No offset/page.
9. Your key may be read-only. If a write returns 403 insufficient_scope, you were issued a read-only API key (scopes: ["read"]) — you can read but not create/update/delete. Tell the user; they can create a full-access key from the dashboard.

​

Common workflows

​

Create a person at a company that may not exist yet

search_companies   {filter: {domain: {equals: "<derived from email>"}}}
  ↓ if 0 results:
create_company     {name: "<inferred>", domain: "<derived>"}
  ↓ save id
create_person      {email, first_name, last_name, primary_company_id: <id>}

​

Who’s the primary contact at a company?

1. Look for custom_attributes.primary_contact_id on the company — that’s the convention.
2. If unset, search_people {filter: {primary_company_id: {equals: <id>}}} — if exactly 1 result, surface them. If multiple, ask the user to designate.

​

Log a meeting

{
  "tool": "log_activity",
  "arguments": {
    "parent_object_type": "person",
    "parent_object_id": "<id>",
    "activity_type": "meeting",
    "occurred_at": "2026-05-25T14:00:00Z",
    "payload": { "topic": "...", "duration_min": 30, "attendees": [] }
  }
}

​

Add a tier field to people

{
  "tool": "add_attribute",
  "arguments": {
    "object_type": "person",
    "attribute_key": "tier",
    "display_name": "Tier",
    "data_type": "enum",
    "enum_values": ["free", "pro", "enterprise"]
  }
}

​

”Create a task” / “Register a webhook” / “Define a custom object” — REST-only

# task
curl -X POST $SALTY_API/tasks \
  -H "Authorization: Bearer $SALTY_API_KEY" -H "Content-Type: application/json" \
  -d '{"parent_object_type":"person","parent_object_id":"<id>","title":"...","due_at":"2026-05-29T17:00:00Z"}'

# webhook (signing_secret in response is whsec_… shown ONCE)
curl -X POST $SALTY_API/webhook-endpoints \
  -H "Authorization: Bearer $SALTY_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://...","subscribed_events":["deal.created"]}'

​

Errors and what to do

​

Out of scope for v1

• Bulk import endpoints (v1.1)
• Search/filter on custom-object records (v1.1)
• Webhook event glob patterns (v1.1)
• Updating an activity’s parent (immutable)
• Company.primary_contact_id field (v1.1 candidate)