Sergio by Serviche

Edit contacts in bulk

edit_contacts

Idempotent

Applies one edit to up to 5000 contacts, as the Contacts page's selection bar does: op add_to_list / remove_from_list (listId), add_tags / remove_tags (tagIds), set_service_category (value residential, commercial, both or null), set_lead_source (value thumbtack, google_lsa, yelp, bark, website_form, google_business_profile, referral, booking_software, direct, web_chat, other or null), set_type (type client, lead, applicant, other), archive, mark_spam (at most 500 for the last three; a type change or spam tags or untags the Quo card when the business's write setting allows). Each contact answers succeeded, skipped (already so) or failed. Pass the same idempotency_key when retrying; every op is safe to repeat.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "ids": "<ids>",
      "op": "<op>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "edit_contacts"
  }
}

Input Schema

Name	Required	Description
`op`	Yes
`ids`	Yes
`type`	No
`value`	No
`listId`	No
`tagIds`	No
`idempotency_key`	Yes	Your id for this operation (8-128 of A-Z a-z 0-9 . _ : -). Reuse it on every retry of the same operation; use a new one for a new operation.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 8, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations it discloses partial-success semantics ('Each contact answers succeeded, skipped (already so) or failed'), the 500-record cap for set_type/archive/mark_spam versus 5000 overall, a conditional side effect on the Quo card gated by a business write setting, and explicit idempotency-retry behavior. That is exactly the extra context the annotations (destructiveHint=false, idempotentHint=true) cannot express on their own.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Everything is packed into effectively one long sentence, but the scope and op list are front-loaded and no clause is filler — each parenthetical earns its place. It is dense enough that a reader must parse carefully, which is the only reason it misses a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-op mutation tool with no output schema, the description still supplies the result shape (per-contact succeeded/skipped/failed), the size limits, the conditional side effect, and retry rules. There is no meaningful gap an agent would need to guess at before calling it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 14%, so the description must carry parameter meaning and it does: it enumerates the allowed values for set_service_category and set_lead_source (including null) and the type enum, and tells the agent which parameter belongs to which op. Without this text the 7-param discriminated schema would be largely opaque.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Applies one edit'), resource (contacts), and hard scope ('up to 5000') in the first clause, and enumerates the exact op vocabulary so the agent knows the tool's full surface. It is clearly distinguishable from sibling single-record editors like edit_contact_tag, edit_contact_list and edit_client because it is explicitly bulk and op-dispatched.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The op-to-parameter mapping ('add_to_list / remove_from_list (listId)', 'set_type (type ...)', etc.) functions as concrete per-operation usage guidance, and 'as the Contacts page's selection bar does' anchors the mental model. It stops short of naming alternatives such as edit_client for single-contact edits or saying when not to use bulk, which keeps it at 4 rather than 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Sergio by Serviche tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?