AIsa Sales

Search for Contacts

post_apollo_contacts_search

Read-onlyIdempotent

Search for contacts. Requires a master API key.

Published reference price: $0.012 USD per successful request. Account-specific pricing and final settlement may differ.

Input Schema

Name	Required	Description	Default
`body`	Yes

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedOct 19, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / body

Added value: +{
+  "properties": {
+    "contact_label_ids": {
+      "description": "The Apollo IDs for the labels that you want to include in your search results. If you add multiple labels, Apollo will include all contacts connected to any of the labels, along with the other parameters, in the search results. Example: `['6095a710bd01d100a506d4ae']`",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "contact_stage_ids": {
+      "description": "The Apollo IDs for the contact stages that you want to include in your search results. If you add multiple contact stages, Apollo will include all contacts that match any of the stages, along with the other parameters, in the search results. Call the [list contact stages endpoint](https://docs.apollo.io/reference/list-contact-stages) to retrieve a list of all the contact stage IDs available in your Apollo account. Example: `6095a710bd01d100a506d4ae`",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "page": {
+      "description": "The page number of the Apollo data that you want to retrieve. Use this parameter in combination with the `per_page` parameter to make search results navigable and improve the performance of the endpoint. Example: `4`",
+      "format": "int32",
+      "type": "integer"
+    },
+    "per_page": {
+      "description": "The number of search results that should be returned for each page. Limiting the number of results per page improves the endpoint's performance. Use the `page` parameter to search the different pages of data. Example: `10`",
+      "format": "int32",
+      "type": "integer"
+    },
+    "q_keywords": {
+      "description": "Add a keyword search string to narrow the contacts in your team's Apollo account. Keywords should be related to the same search concept and can include names, job titles, employers or company names, or email addresses. Examples: `matthew helm`; `CEO`; `Sumware Software`",
+      "type": "string"
+    },
+    "sort_ascending": {
+      "default": false,
+      "description": "Set to `true` to sort the matching contacts in ascending order. This parameter must be used with `sort_by_field`. Otherwise, the sorting logic is not applied. Example: `true`",
+      "type": "boolean"
+    },
+    "sort_by_field": {
+      "description": "Sort the matching contacts by 1 of the following options: \n- `contact_last_activity_date`: The most recent activity date recorded first.\n- `contact_email_last_opened_at`: The most recent email opened date first.\n- `contact_email_last_clicked_at`: The most recent email clicked first.\n- `contact_created_at`: The most recently created first.\n- `contact_updated_at`: The most recently updated first.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

removedInput schema / properties / contact_label_ids

Removed value: -{
-  "description": "Filter by contact label IDs",
-  "type": "string"
-}

removedInput schema / properties / contact_stage_ids

Removed value: -{
-  "description": "Filter by contact stage IDs",
-  "type": "string"
-}

removedInput schema / properties / page

Removed value: -{
-  "description": "Page number",
-  "type": "integer"
-}

removedInput schema / properties / per_page

Removed value: -{
-  "description": "Items per page",
-  "type": "integer"
-}

removedInput schema / properties / q_keywords

Removed value: -{
-  "description": "Keyword query",
-  "type": "string"
-}

removedInput schema / properties / sort_ascending

Removed value: -{
-  "description": "Sort ascending. Default false.",
-  "type": "boolean"
-}

removedInput schema / properties / sort_by_field

Removed value: -{
-  "description": "Sort field (e.g. contact_last_activity_date, contact_created_at, contact_updated_at)",
-  "type": "string"
-}

changedInput schema / required

Previous value: -[]New value: +[
+  "body"
+]

First observedSep 15, 2026

TDQS

C2.8/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds two genuinely useful non-schema facts, the master API key requirement and the per-request price, but says nothing about result volume, rate limits, or account scoping. Given annotations carry most of the burden, a 3 is appropriate.

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?

The core content is two tight sentences with the purpose front-loaded. The pricing block is injected boilerplate rather than authored prose, but it is fenced and does not bury the actual intent.

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

Completeness3/5

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

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. What is still missing is routing against the numerous sibling search tools and any hint about the nested body structure, which for a nested-object, open-world search endpoint leaves meaningful gaps.

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

Parameters2/5

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

Schema description coverage is reported at 0% for the top-level required parameter 'body', and the description says nothing at all about how to shape the body. Although the nested properties carry their own descriptions in the schema, the description contributes zero additional meaning about pagination, keyword search, sorting, or label/stage filters, so it fails to compensate for the coverage gap.

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

Purpose3/5

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

The description names a clear verb and resource ('Search for contacts'), so the basic purpose is legible. However, it gives no differentiation from the many sibling contact/search tools (e.g. get_apollo_contacts_contact_id, post_apollo_mixed_people_api_search), leaving the agent to guess which is appropriate. This lands at the minimum-viable level rather than a specific, distinguishing statement.

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

Usage Guidelines2/5

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

Only 'Requires a master API key' is offered, which is a prerequisite rather than guidance on when to use this tool versus alternatives. Nothing tells the agent when this search is preferred over the mixed-people or bulk-match siblings, and there are no exclusions or context cues.

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

All AIsa Sales 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?