Tool catalogue
Every tool has a JSON input schema, a description written for agents, and annotations (readOnlyHint,
destructiveHint, idempotentHint). Every write tool also takes dryRun (validate, compute, roll back) and
idempotencyKey (≤ 200; the same key returns the first result). On a multi-account connection
every tool also takes accountId.
Tools marked listed with scope only appear in tools/list when the key or connection has that scope. The
others are always listed; calling a write without records:write returns a FORBIDDEN tool error.
Start here
Section titled “Start here”| Tool | Does | Key inputs | Scope |
|---|---|---|---|
whoami |
Your agent, account (name, base currency, timezone), scopes and key. Call it first | none | any |
describe_crm |
The schema in one call: objects, fields, enums, filterable fields and ops per type, upsert match keys, relative times, this account’s pipelines with stages, and its custom fields with the ops each takes | none | records:read |
list_accounts |
The accounts of a multi-account OAuth connection, with the agent and scopes in each. Only on such connections | none | any |
| Tool | Does | Key inputs | Scope |
|---|---|---|---|
search |
Find organizations, contacts and deals by name, email or domain. Search before you create | query (2–200), types?, limit? (1–50) |
records:read |
query_records |
Filtered, sorted, paged lists | type (organization|contact|deal), filters? (≤ 30 { field, op, value }), sort?, page?, perPage? (≤ 100), fields?, q? |
records:read |
get_record |
One record by id | type (also activity), id, include?: contacts, deals, organizations, timeline (last 20 activities, compact) |
records:read |
get_timeline |
Activities of an organization (and its contacts), a contact or a deal, newest first | type, id, limit?, cursor?, compact? (default true) |
records:read |
list_activities |
Activities across the account | type? (comma list), from?, to?, contactId?, organizationId?, dealId?, limit?, cursor?, compact? (default true) |
records:read |
get_history |
Who changed what on a record: action, actor, surface, field changes | type, id, limit?, cursor? |
records:read |
list_pipelines |
Pipelines with ordered stages (id, name, outcome, probability) | status? (active|archived|all) |
records:read |
get_board |
A pipeline as its Kanban board: stages with active deals in order, counts, totals per currency | pipelineId, q? |
records:read |
pipeline_metrics |
Open, weighted, MRR/ARR, won this month per pipeline and currency; totals incl. contacts not contacted in 48 h | pipelineId? |
records:read |
list_custom_fields |
The account’s custom field definitions | entityType?, status? |
records:read |
list_feedback |
This account’s feedback with status and the Mety team’s response | status?, kind?, page?, perPage? |
records:read |
list_audit_events |
The account’s audit log | entityType?, entityId?, actorType? (user|agent), actorId?, limit?, cursor? |
listed with audit:read |
Write records
Section titled “Write records”| Tool | Does | Key inputs | Scope |
|---|---|---|---|
upsert_records |
Create or update up to 100 records by natural key. Missing or empty values never overwrite (unless nullOverwrites); tags, customFields, externalRefs merge. Per-item created/updated/unchanged/error |
type, matchOn (organizations domain|taxId|id|externalRef:<system>; contacts email|id|externalRef:<system>; deals id|externalRef:<system>), items (1–100), nullOverwrites? |
records:write |
create_record |
One organization or contact with no natural key (no domain, tax id or email). Otherwise prefer the upsert. Duplicate → DUPLICATE with the existing id |
type (organization|contact), fields |
records:write |
update_record |
Change fields of an organization, contact, deal or activity. null clears; tags/customFields/externalRefs replace; customFieldsMerge merges; a deal’s stageName moves it |
type, id, changes, version? |
records:write |
create_deal |
A deal in a pipeline and stage, linked to organizations and contacts | name, pipelineId?, stageId? / stageName?, amountCents?, currency?, revenueType?, billingInterval?, expectedCloseOn?, organizationIds? or organizations? (with roles), contactIds? or contacts?, lostReason?, tags?, customFields?, externalRefs? |
records:write |
move_deal |
Move a deal to another stage of its pipeline. Won/lost sets closedAt; open clears it and lostReason |
dealId, stageId? / stageName?, lostReason?, position?, version? |
records:write |
link_records |
Link contact↔organization, deal↔organization or deal↔contact (either order). Linking again updates role / primary | from: { type, id }, to: { type, id }, role?, isPrimary? |
records:write |
unlink_records |
Remove one of those links. The records stay | same | records:write |
log_activity |
One activity (fields at the top level) or up to 100 (items). externalId dedupes; autoLink links participants |
type, direction?, occurredAt?, subject?, body?, durationSeconds?, participants?, externalId?, contactIds?, organizationIds?, dealIds?, autoLink?, source? (import) — or items |
records:write |
archive_record |
Archive an organization, contact or deal (reversible: update_record with status: "active") |
type, id |
records:write |
delete_record |
Hard-delete an organization, contact, deal or activity. Irreversible | type, id |
listed with records:delete |
send_feedback |
Tell the Mety team what is missing or broken. A person reads it | kind (bug|idea|missing_feature|question|other), title, body, page? |
feedback:write |
Pipelines and stages
Section titled “Pipelines and stages”All listed with pipelines:manage.
| Tool | Does | Key inputs |
|---|---|---|
create_pipeline |
A pipeline with ordered stages (default Lead, Qualified, Proposal, Negotiation, Won, Lost); ≥ 1 open, exactly 1 won | name, description?, stages?: [{ name, probability?, outcome? }] |
update_pipeline |
Rename, describe, make default, archive/restore, reorder | pipelineId, name?, description?, isDefault?, status?, position? |
delete_pipeline |
Delete an empty, non-default pipeline | pipelineId |
add_stage |
Add a stage | pipelineId, name, probability?, outcome?, position? |
update_stage |
Rename, change probability or outcome | stageId, name?, probability?, outcome? |
delete_stage |
Delete a stage; with deals, moveDealsTo is required (else STAGE_NOT_EMPTY) |
stageId, moveDealsTo? |
reorder_stages |
Set the order: exactly the pipeline’s stages | pipelineId, stageIds |
Custom field definitions
Section titled “Custom field definitions”All listed with fields:manage.
| Tool | Does | Key inputs |
|---|---|---|
define_custom_field |
Type a customFields key so writes are validated and coerced and lists filter and sort by it. meta.existingValues / meta.invalidValues |
entityType, key, label: { es, en? }, type, options?, description?, showInList?, listPosition?, filterable? |
update_custom_field |
Labels, options, description, display, archive/restore. key and type never change |
id, label?, options?, description?, showInList?, listPosition?, filterable?, status?, version? |
delete_custom_field |
Delete the definition; values stay in customFields, untyped |
id |
Untrusted content
Section titled “Untrusted content”get_record (activities and timeline), get_timeline, list_activities, log_activity and update_record on an
activity return activity text under untrustedContent: { subject, body } instead of subject / body. Their
descriptions tell the model it is third-party data and must not be obeyed.
Examples
Section titled “Examples”{ "name": "upsert_records", "arguments": { "type": "organization", "matchOn": "domain", "items": [{ "name": "Acme Inmobiliaria", "domain": "acme.es", "lifecycle": "prospect" }], "dryRun": true } }{ "name": "move_deal", "arguments": { "dealId": "…", "stageName": "Won", "version": 6, "idempotencyKey": "won:acme-annual" } }{ "name": "link_records", "arguments": { "from": { "type": "contact", "id": "…" }, "to": { "type": "organization", "id": "…" }, "role": "CFO", "isPrimary": false } }More in the recipes.